[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Savannah-dev] Savannah/CodeX documentation - Next steps?
From: |
Laurent Julliard |
Subject: |
[Savannah-dev] Savannah/CodeX documentation - Next steps? |
Date: |
Mon, 29 Apr 2002 16:46:09 +0200 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.0rc1) Gecko/20020417 |
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
- [Savannah-dev] Savannah/CodeX documentation - Next steps?,
Laurent Julliard <=