It would be easier to see, if a translated document is up to date or not. Additional I want to suggest to change the table of content, cause all the links for language 1 to N make it more confusing than readable. Instead of adding a link for each language, I propose to use a two column table with the document title on the left and english/browser_locale/other (maybe represented as icons) on the right and/or a list of all available translations incl. revision at the top of each document. Reproducible: Always Steps to Reproduce: 1. 2. 3.
Conserning the layout change of the docs page: there is a suggestion being discussed now, which proposes to create $LANG.gentoo.org sites, each of them would maintain there own copy of the docs page as well as of some others. GLEP #10: http://www.gentoo.org/proj/en/glep/glep-0010.html
Read it, but internationalization does't help if the localisations are not up to date. I don't see there any note about visible version numbers in the header of the document, to give the user information, if the localised doc is the newest one, or if it's better to read the english version. And I would still prefer an index, where i can decide which language I'll give a try.
well, does it matter so much if theres a version # as the date ? in the upper right theres a date that shows last time the file was updated
It is a Good Practice if there is a comment on what revision number the translation is synchronised with (as is the case with the dutch translations). The upcoming GDP Documentation HOWTO contains a paragraph for adding such a comment, but it isn't mandatory. It is up to the translation team to know how they manage their translations.
>well, does it matter so much if theres a version # as the date ? Yes it matters. Cause you have still to lookup the english version, if it's newer or not. Only the version/date of the translated document is not enough in my eyes. Additional I prefer version numbers, because you have these major.minor numbering, which could show if a document is totally rewritten or only a paragraph changed/was added. A date cannot provide this.
The installation guide is updated on a daily basis; the chance that your translation is uptodate is very slim. Having a $Revision: blabla$ shown to the users is very ugly. Using version numbers is good as long as they are really changed each update, which is currently not the case.
>Having a $Revision: blabla$ shown to the users is very ugly. Hm, I don't think so. I prefer to get as much metadata as possible. >Using version numbers is good as long as they are really changed each update, which is currently not the case. That's another problem. Not only affecting documentation, but eclasses and ebuilds too. Imho every change should result in a new revision.
I still don't agree with placing revision history. You might think that metadata is good, but I'm pretty sure the end user rather wants a clear guide than a guide filled with metadata. However, I'll propose to add to the documentation policy that any change to english documentation must result in an upgrade of the <version>...</version> information, and that translations should make sure that this version is copied verbatim. Please check the gentoo-doc mailinglist and follow the discussion (if there is one).
Sven: Sorry for being insistent, but I think you got me wrong. I don't want a revision history, but a possibility to give the user a fast overview, which documetation is not up to date. An example: As i used the Alternative Installation Guide a year ago, the german version was totally outdated. I read first the german and after it the english version. Reading it in german was a total waste of time. >Please check the gentoo-doc mailinglist and follow the discussion (if there is one). Don't get me wrong; I never liked mailing lists. ;-)
I'm going to add information to the documentation policy that the version number of the document - must be increased when the document is altered, except in some circumstances where such an increase of version information isn't needed - must be the same as the version number of which the translation is in sync, if the document is a translation ofcourse This should fix this problem.
Thx! I think the addressees of these Guides will appreciate this.
Thnaks to Sven we now have this in Documentation Policy, so I can close the bug.
