- Admin documentation are is in Info format (texi), The FAQ uses plain
HTML files and some other help files are historically PHP
- There is no way to generate a user manual from all these pieces of
help files.
- Savannah lacks end-uder documentation (I mean documentation of the
Services themselves) and could therefore re-use a lot from the CodeX
User Guide.
So I guess my questions here is can we use a format for the
documentation that would allow for:
- The generation of both HTML, Postscript and PDF formats.
- The HTML should be generated into pieces and it should be able to
generate CSS based HTML to take advantage of a "help" css file that
can vary from one site to another.
- Each chunck of HTML could be re-used by the SAvannah/CodeX online
help (for an example of the SAvannah on-line help see the '?' in the
new bug tracking system)
- So from the previous point there is a need to indentify a specific
section of the master document and point to it.
- Probably a need for connditional generation (the content may change
from one site to another or from one format to another)
- Include images (for screenshots or other)
Can the tex info format do all this? Is the DocBook format better? or
others?
Recently, I've have added a FAQ system that permit us to add anwser to
FAQ in a simple way, we just need to add a file in the doc/site/faq dir.
And a PHP page generated a texi version of the faq (that should be tested).
The questions in the FAQ are the ones that have been the purpose of
several support request. I think that we should let this FAQ distinct
from others documents, if we include it in a more global help system.
About texi :
The texinfo is the standard for the GNU project, and savannah is a part
of the GNU project
http://www.gnu.org/prep/standards_33.html
But "Nowadays some other formats such as Docbook and Sgmltexi can be
converted automatically into Texinfo. It is ok to produce the Texinfo
documentation by conversion this way, as long as it gives good results."
About (?) it's nice but personnaly I think that the site should be easy
to use and we shouldnt make reference to many many different page (also,
for text browser, popup is a pain). For example, about
http://savannah.gnu.org/support/?group_id=11
I dont find really usefull to add (?) explaining the 3 fields.
Basically, everybody understand what it is about fast, no ?
Also, IMHO the link to the Generic Documentation, in fact the SF
installation guide, should be elsewhere than in the left menu. There's
probably only a few people that want to install savannah and it's
usefull only for admins. So a link in Admin Documentation would do the job.
A normal user searching for documentation will easily understand what «
admin documentation » is about, but « generic documentation » can be
many things, it can be confusing to have 3 links to documentation in the
principal menu.