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

Tom Fifield tom at openstack.org
Tue Oct 29 01:38:57 UTC 2013


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



More information about the Openstack-docs mailing list