Documentation proposal

[Jari Rahkonen]

Mike Massonnet wrote:
> 2009/5/4 Brian J. Tarricone <bjt23 at cornell.edu>:
>> Related to synchronisation, the main benefit is that it's easier to tell
>> what's changed -- that is, if I go and change one sentence in the English
>> docs, rebuilding the .po files will make it very easy for the translator to
>> figure out what I changed without having to read through the entire doc.
> 
> Sync the doc allows it to be mixed with english texts. Figuring that
> syncing the translated doc is not possible, one good way would be to
> have a trunk/ that is an in-progress documentation and english-only.
> Than existing branches would exist for stable docs for specific
> versions of the components and are freezed, and those would be allowed
> to contain translations.
> 
> It is easy to let the translator know which documentations can be
> translated. I guess that's the best option I can come up with, that is
> easy and doesn't let the doc being provided with different locales
> while most of them could be out of sync. Very very annoying.

As a translator I'm all for simpler markup and getting rid of 
docbook/gettext in documentation. As Brian said in a recent mail, the 
translation of UI strings and documentation need to be handled as two 
separate tasks with different workflows (and problems). Off the top of 
my head I can only think of the following as a solution to the question 
of synchronisation:

Design a doc translation statistics web script that keeps track of 
changes to documentation files in git. The page would list all packages 
for which documentation exists and the status of their translations by 
language.

The status of a particular documentation file would be one of the following:

1. No translation to selected language exists. A link to the current
    English source documentation file could be provided.
2. The documentation file has been changed since the translation
    was last updated. In addition to the source download link there would
    be a link to the translated file in git and a way to see a diff of
    all commits to the English documentation since the last translation
    update. The implementation of this functionality would be based on
    commit timestamps and git output.
3. Translation is up to date.

Comparing to gettext, a direct correlation between strings / parts of 
documentation files and their translations would not exist, so the exact 
number of strings that need to be translated wouldn't be as easily 
available. Breaking the documentation to smaller files would partially 
alleviate this problem. The status of any docs that need a translation 
update could additionally show the number of added/removed/changed lines 
in the diff.

Documentation changes that do not require translation updates (typo 
fixes and such) would show as "false positives" in the translation 
statistics, but I'm sure this could be worked around somehow.

I could try to find some time to help with the design and implementation 
of the system if the idea is found to be workable.

- Jari