Open Stack

On Tue, Mar 31, 2015 at 11:26 AM, Karen Bradshaw <kbhawkey at gmail.com> wrote:

> Hi.  I have a few thoughts about the actual migration process.  I migrated
> several
> files and made a few rookie mistakes.
>

Great questions, I'll answer inline. Thanks a bunch for pitching in!


> -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.
>

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
https://wiki.openstack.org/wiki/Documentation/Migrate#Migration_How_To for
instructions.

If you want to work on the theme itself, you're welcome to review changes
in progress at
https://review.openstack.org/#/q/project:openstack/openstackdocstheme,n,z



> -I tried pandoc, but did not find the translation very complete.
>

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."


> -Even though there is a guide for replacing DocBook markup with RST markup,
> 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?
>

Sure, the openstackdocstheme is where we'd do that work. Feel free to log
doc bugs in http://bugs.launchpad.net/openstack-manuals 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.


> -How do you validate the content of the migration?  How to test the new
> links for each migrated document?
>

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.

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.

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.

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.


> -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.
>

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
http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#tables for
inspiration.

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
https://pythonhosted.org/cloud_sptheme/lib/cloud_sptheme.ext.table_styling.html#module-cloud_sptheme.ext.table_styling.
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.


> -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?
>

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%.

You can view the patches in progress as you review the migrated content by
clicking the gate-openstack-manuals-tox-doc-publish-checkbuild
<http://docs-draft.openstack.org/72/168772/5/check/gate-openstack-manuals-tox-doc-publish-checkbuild/cbebdd7//publish-docs/>
in
the Jenkins check column on any patch in review.openstack.org that has the
user guide content. For example,
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


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
http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-web-design.html
if
you want to deep dive on what issues we're addressing with the new design.

Hope these explanations help. Great questions, feel free to ask more.
Thanks,
Anne


> Thanks!
> Karen
>
>
> On Tue, Mar 31, 2015 at 1:58 AM, Andreas Jaeger <aj at suse.com> wrote:
>
>> On 03/31/2015 03:32 AM, Anne Gentle wrote:
>>
>>> Hi all,
>>>
>>> Thinking on what the criteria for the next guide to go to RST, I wanted
>>> us to consider these data points. I mentioned this need in the last doc
>>> team meeting.
>>>
>>> Our goal is to have a sense of not only "what's next" but also the
>>> ability to answer why a guide is next, especially if (since) we're
>>> crunched for time and resources.
>>>
>>> 1. Number of readers based on web analytics from Google Analytics, such
>>> as unique page views per time period.
>>> 2. Number of contributors in the last two releases (one calendar year of
>>> data) from Stackalytics or git.
>>> 3. Ease of migration - size of guide or simplicity of guide.
>>> 4. Automation efforts - what amount of the guide is auto-generated and
>>> does that make it easier to migrate what remains (or possibly more
>>> difficult).
>>>
>>> Any other criteria you can think of, just write back to the list so we
>>> can discuss further. I'm sure I haven't thought of everything so bring
>>> your data ideas.
>>>
>>
>> 5. Conditionals - a guide without any conditionals is easier. Getting the
>> User Guides separated was non-trivial,
>>
>> 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,
>>
>> Andreas
>>
>> --
>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>    GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
>>        Graham Norton, HRB 21284 (AG Nürnberg)
>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150331/f3c0aa05/attachment-0001.html>