[RFC] doc directory reorganisation & I18N

[Robert Collins]

On Thu, 2007-08-02 at 10:09 +1000, Ian Clatworthy wrote:
> 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.

It sounds good. We already do 6 right? Or are you suggesting some change
there?

-Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20070802/b7307140/attachment.pgp