Open Stack

Hi.  I have a few thoughts about the actual migration process.  I migrated
several
files and made a few rookie mistakes.
-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.
-I tried pandoc, but did not find the translation very complete.
-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?
-How do you validate the content of the migration?  How to test the new
links for each migrated document?
-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.
-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?
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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150331/87ae7b87/attachment.html>