[Savannah-dev] Savannah/CodeX documentation - Next steps?

[Laurent Julliard]

All,

I'd like to start a discussion around documentation here. I know this is 
not one of the favorite topic of developers but this is a crucial part 
of a project like Savannah (or CodeX at Xerox).

The reason Iask this question is because I have written a 100+ page user 
manual for our CodeX site at Xerox and we want to contribute this manual 
to Savannah. Of course an obvious solution is to deliver a PDF version 
of the document as is but I don;t like this idea. It is my impression 
that both Savannah and CodeX could make progress on this topic:

CodeX
-----
- User Manual native format is currently MS-Word (aargh!)
- It is a monolithic document and CodeX online help system cannot be 
derived from this manual... (not good)


Savannah
--------
- 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?

Any idea and comment welcome.

LJ