[Openstack-docs] proposed rst-xml automation openstack-manuals blueprint

Nermina Miller nerminamiller at gmail.com
Tue Oct 29 12:18:19 UTC 2013


Tom, these files could be kept in the currently proposed Sources folder
within the Training Guides folder. Would that alleviate your concerns?
However, these devref files contain valuable install information that could
be included in other guides. I could analyze them further to see how they
could be appropriated. If there's no significant value that would make them
xi:includable for other guides, then they could be hosted in the Training
folder. The ultimate intent is to make them accessible and part of the OS
Docs family. I would think that translators would focus only on the files
that are particular to a specific guide and not the entire Common folder. I'll
respond to Anne's comments shortly. - Nermina

On Monday, October 28, 2013, Tom Fifield wrote:

> On 29/10/13 11:45, Nermina Miller wrote:
> > - Add the entire batch of the devref files to the Common folder
> > (subfolder Training) so the files can be made available to the other
> > guides in the long term. (Why all? Because the py script updates and
> > converts them ALL at the same time. You may already know this but it
> > helps to explain the need for such a large batch.)
>
> This is a problem for translation.
>
> The common directory is already over 50,000 words - putting it beyond
> the reach of all but our most dedicated language teams. I've actually
> had a plan to try and move some material that really isn't 'common' out
> of there for this reason.
>
> Using common as a dumping ground will essentially prevent translation of
> the best parts of our manuals - those that have been lovingly crafted
> for use in several documents. Translators should be able to make maximum
> impact by translating items in common, but that's not true today.
>
> For a real example, take the install guide - it's just 18k words, a nice
> small guide and easy to translate. There's actually some good progress
> being made in several languages (more than 20% in Russian and Chinese).
> However, it also has some content from common, and working with the 50k
> mess to get a complete document out is pretty annoying.
>
> In short: please don't put stuff in common unless it is truly used by
> multiple documents, and especially don't use it as a dumping ground for
> large amounts of content.
>
>
>
> Regards,
>
>
> Tom
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org <javascript:;>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>


-- 
Thank you!

Nermina Miller
Tech Writer and Editor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131029/071d5b53/attachment.html>


More information about the Openstack-docs mailing list