Developers of Sympa

[Olivier Salaün - CRU <address@concealed>]

address@concealed wrote:     [...]
     Three Standard Docs:
       1 installation manual (but not upgrade info)
       2 administrator's manual (would include upgrade info)
       3 list administrator / list owner cookbook
(1) is currently provided as a light version (INSTALL file) and a longer but probably too detailed version (Chapter 3 of the documentation).
(2) is the reference manual : http://www.sympa.org/doc/html/
(3) how different is it from (4)
We also need a (3bis) contributor / developer documentation that provide advanced informations about the code, templates, catalogs design. Chapter 28 of the doc would move to this document.
     Two Generic Docs designed to be easily customized for particular site requirements and policies:

       4 list owner's manual
       5 subscriber guide (very brief)
Both (4) and (5) will be available soon thanks to Virginie.
     Yes, there would be some duplication of information across some of these manuals, but for ease of use from the reader's
     perspective, this approach makes a lot of sense.  To prevent unnecessary duplication, the documentation platform would
     need to provide good tools for maintaining accurate cross references both as physical page citations as well as hyper-links, depending upon the output format.
I think you're right : it's better to separate these documentation because :

• Some of these need to be short (install guide), others longer (administrator's manual)
• Some will be internationalized (4 and 5) whereas translating (2) would be a nightmare.
• These documents might be maintained by different people

I'd like to have your point of view on the i18n mechanism we have adopted for (4) and (5) :
In the past we used to maintain a set of different templates for each supported language. When we reached up to 15 languages it was no more maintainable. We have then adopted a single set of templates, language neutral, with references to catalogs ([% |loc %]) and we now have all translatable strings gathered in each language gettext catalog. This mechanism drawback appears while translating online documentation : the translator has very long sentences to translate and does not have the context while doing the translation. Therefore we've decided to split the user documentation into different set of templates. The main drawback of this choice : keeping track of obsolete / changed / new strings will be hard.
Here is the new organization from our CVS : http://sourcesup.cru.fr/cgi/viewcvs.cgi/sympa/web_tt2/fr_FR/