<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Mar 31, 2015 at 11:26 AM, Karen Bradshaw <span dir="ltr"><<a href="mailto:kbhawkey@gmail.com" target="_blank">kbhawkey@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Hi. I have a few thoughts about the actual migration process. I migrated several<div>files and made a few rookie mistakes.</div></div></blockquote><div><br></div><div>Great questions, I'll answer inline. Thanks a bunch for pitching in!</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-It would be useful to edit/test the theme that is publishing the docs in the sandbox. Perhaps this is already possible, I have not investigated how to build the theme and apply it to my local doc repository.</div></div></blockquote><div><br></div><div>Yes, absolutely this is possible. What's happening now is the theme is developed in openstackdocstheme and applied to playground-user-guide when you build using the tox tests in the openstack-manuals repo. Take a look at <a href="https://wiki.openstack.org/wiki/Documentation/Migrate#Migration_How_To" target="_blank">https://wiki.openstack.org/wiki/Documentation/Migrate#Migration_How_To</a> for instructions. </div><div><br></div><div>If you want to work on the theme itself, you're welcome to review changes in progress at <a href="https://review.openstack.org/#/q/project:openstack/openstackdocstheme,n,z" target="_blank">https://review.openstack.org/#/q/project:openstack/openstackdocstheme,n,z</a> </div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-I tried pandoc, but did not find the translation very complete.</div></div></blockquote><div><br></div><div>Well, it's complete as in, nothing is lost, but there is a lot of manual clean up after pandoc does what it can. So talk more about "complete" if you're losing data. If you're losing formatting, well, that's why we have to manually clean up and quality-check patches of migrated content. The manual cleanup is a big part of why I want criteria for "what's next to be migrated."</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-Even though there is a guide for replacing DocBook markup with RST markup,</div><div>sometimes the html produced, using the new RST markup, is not what you expect. For example, text publishes italic vs. bold, text spacing. Should you improve on the new doc output if possible?</div></div></blockquote><div><br></div><div>Sure, the openstackdocstheme is where we'd do that work. Feel free to log doc bugs in <a href="http://bugs.launchpad.net/openstack-manuals" target="_blank">http://bugs.launchpad.net/openstack-manuals</a> with the tag "openstackdocstheme" and we'll triage what we want to prioritize. Still, we have our style and markup guide. To me, the main idea is to encourage more contributors so less is more when it comes to markup.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-How do you validate the content of the migration? How to test the new links for each migrated document?</div></div></blockquote><div><br></div><div>Our checklinks test at the gate should still be a valid test of the links in the document. What we'll need to do is see if we have to do redirects in our .htaccess file, which you can patch in openstack-manuals/www/static/.htaccess.</div><div><br></div><div>Ideally we'll ditch that extra /content/ directory in the URL but keep the xml:ids identical so the HTML files output from RST match the ones that were originally output with DocBook. </div><div><br></div><div>If that answer is completely unparsable, I'd be happy to walk through more in real-time chat. :) I'm not trying to obfuscate any part of the migration.</div><div><br></div><div>We will have to do side-by-side comparisons of the output, Andreas has started doing patches where he has done that to get the ordering correct and so on.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-Tables. Creating line art tables is time consuming. Are all the tables formatted in a standard way. It would be useful if Sphinx could take an existing html table and process into RST table markup.</div></div></blockquote><div><br></div><div>Yes. Agreed wholeheartedly. Tables are awful to create and maintain in Sphinx. I mean, there are ways to have more ways to make table editing and output less awful, refer to <a href="http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#tables" target="_blank">http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#tables</a> for inspiration. </div><div><br></div><div>Also, I don't like the non-responsive, non-fluid design of our current theme but for this first iteration it's fine. To get truly fluid tables we'll probably have to do some CSS work and some extension work, see <a href="https://pythonhosted.org/cloud_sptheme/lib/cloud_sptheme.ext.table_styling.html#module-cloud_sptheme.ext.table_styling" target="_blank">https://pythonhosted.org/cloud_sptheme/lib/cloud_sptheme.ext.table_styling.html#module-cloud_sptheme.ext.table_styling</a>. That said, I don't want to go to that for this first migration, let's just work with what we have for now and try to eliminate tables that aren't completely necessary. Go with definition lists, bulleted lists, anything but tables. Save your wrists for more writing.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>-So far, I have viewed the playground docs using Chrome on Ubuntu. What do the new docs look like on other browsers/platforms. Are the new docs just as usable as the old docs?</div></div></blockquote><div><br></div><div><div>Based on analytics, we "only" need to test on Chrome and Firefox to get 85% of the traffic from the last 15 months. Windows is 55% of the OS traffic in the same timeframe with Linux at 23% and Mac at 17%.</div><div><br></div><div>You can view the patches in progress as you review the migrated content by clicking the <a href="http://docs-draft.openstack.org/72/168772/5/check/gate-openstack-manuals-tox-doc-publish-checkbuild/cbebdd7//publish-docs/" style="color:rgb(6,84,172);text-decoration:none;font-family:sans-serif">gate-openstack-manuals-tox-doc-publish-checkbuild</a> in the Jenkins check column on any patch in <a href="http://review.openstack.org">review.openstack.org</a> that has the user guide content. For example, <a href="http://docs-draft.openstack.org/72/168772/5/check/gate-openstack-manuals-tox-doc-publish-checkbuild/cbebdd7//publish-docs/playground-user-guide/content/index.html">http://docs-draft.openstack.org/72/168772/5/check/gate-openstack-manuals-tox-doc-publish-checkbuild/cbebdd7//publish-docs/playground-user-guide/content/index.html</a> </div></div><div><br></div><div>To me, the design is more usable, as a detailed design brief was what informed the new design. We have a two-year-old doc bug that this design addresses also. See the links within <a href="http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-web-design.html" target="_blank">http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-web-design.html</a> if you want to deep dive on what issues we're addressing with the new design.</div><div><br></div><div>Hope these explanations help. Great questions, feel free to ask more.</div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>Thanks!</div><span><font color="#888888"><div>Karen</div><div><br></div></font></span></div><div class="gmail_extra"><br><div class="gmail_quote"><div><div>On Tue, Mar 31, 2015 at 1:58 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br></div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><div><span>On 03/31/2015 03:32 AM, Anne Gentle wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Hi all,<br>
<br>
Thinking on what the criteria for the next guide to go to RST, I wanted<br>
us to consider these data points. I mentioned this need in the last doc<br>
team meeting.<br>
<br>
Our goal is to have a sense of not only "what's next" but also the<br>
ability to answer why a guide is next, especially if (since) we're<br>
crunched for time and resources.<br>
<br>
1. Number of readers based on web analytics from Google Analytics, such<br>
as unique page views per time period.<br>
2. Number of contributors in the last two releases (one calendar year of<br>
data) from Stackalytics or git.<br>
3. Ease of migration - size of guide or simplicity of guide.<br>
4. Automation efforts - what amount of the guide is auto-generated and<br>
does that make it easier to migrate what remains (or possibly more<br>
difficult).<br>
<br>
Any other criteria you can think of, just write back to the list so we<br>
can discuss further. I'm sure I haven't thought of everything so bring<br>
your data ideas.<br>
</blockquote>
<br></span>
5. Conditionals - a guide without any conditionals is easier. Getting the User Guides separated was non-trivial,<br>
<br>
Btw. let's do it slowly, we can convert one guide after the other and still have some questions to answer like how to handle the glossary,<br>
<br>
Andreas</div></div><span><font color="#888888"><div><div><br>
-- <br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,<br>
Graham Norton, HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
<br></div></div><span>
______________________________<u></u>_________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</span></font></span></blockquote></div><br></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>