[RFC] doc directory reorganisation & I18N

[Alexander Belchenko]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ian Clatworthy пишет:
> It's rubber-hits-the-road time now for changing the organisation of
> documentation within our source tree. The feedback on the documents I
> want to see has been positive so I'm planning to proceed on the
> assumption that everyone is happy enough with the proposed outcome, i.e.
>  "Current Documentation" in the new look
> http://bazaar-vcs.org/Documentation.
> 
> Here's what I'm suggesting w.r.t. layout under our 'doc' directory:
> 
> index.txt
> developers/   (as now)
>   index.txt
>   ...
> en/
>   index.txt
>   mini-tutorial/
>   quick-reference/
>   user-guide/
>     (most of the existing docs)
>   user-reference/
>   switcher-guides/
>   migration-guide/
>   release-notes/
>   developer-guide/
> xx/
>   (subset of en tree reflecting what has been translated)
> 
> Highlighting the main points:
> 
> 1. We put a structure in place now to support multiple languages
> 2. As a rule, 1 directory per document (or theme) below that
> 3. existing developer stuff stays where it is now
> 4. For English, the doc build process will copy and/or generate the
>    content for some documents, namely:
>    * embedded help -> user-reference (as agreed previously)
>    * NEWS -> release-notes
>    * selected stuff from developers/ -> developer-guide
> 5. For non-English, translations of one or more docs can be maintained
>    directly within the tree, including translations of the generated
>    content (user-reference, release-notes, developer-guide).
> 6. The whole tree below doc/ can be pushed to doc.bazaar-vcs.org/nnnn
>    and that website will have comprehensive docs for each release in
>    one or more languages.
> 
> Does this sound good to everyone? If not, please suggest what you'd like
> to see instead.

I just wondering: how you guys will be review and approve documentation
translations on languages that you don't understand? Per example,
I can translate to russian, but how my translations will be merged?
Of course, there is several people in ML from russian-speaking countries,
but most of them can't vote in BB.

Another side note: the more translations we have the bigger doc/ directory
will grow. May be it worth to extract it in separate sub-project
(aka nested tree?).

/me just don't completely understand all formal details.

- --
[µ]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGsWJ2zYr338mxwCURAh65AJ4h4LXfn8wU4yBye9JxIyn7UTWvWQCaA8TM
/fipXavEn1mO26tDRS5z2DI=
=GSDi
-----END PGP SIGNATURE-----