[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Savannah-dev] Savannah/CodeX documentation - Next steps?
From: |
Mathieu Roy |
Subject: |
Re: [Savannah-dev] Savannah/CodeX documentation - Next steps? |
Date: |
Mon, 29 Apr 2002 17:25:46 +0200 |
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:
For a documentation about a website, Postcript / PDF arent really
interesting : the website should be enough easy to understand that
users dont require to print a 100+ page doc :)
Basically, PS and PDF is good for printing or for getting help offline.
It's good for programming langages, read books, but if it's needed to
understand how savannah works, maybe savannah doesnt fit to what it
should be.
But it dont think it is the case, so...
- 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.
--
Mathieu Roy
* http://savannah.gnu.org/users/yeupou
* http://yeupou.coleumes.org
* http://gpg.coleumes.org (GPG Key)