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
