On Thu, 7 Aug 1997, Rodent of Unusual Size wrote:
> I'd like to propose that this list be set up so that the $SENDER is
> the list address ("apache-docs"), the way NH is but JSDK isn't. I
> find it makes sorting through what I want to read in what order much
> simpler than trying to check the "to" or "cc" lines.
Second that...
Ok, this is my view on the topic of ADP (feel free to yell and
argue). I have a short list of topics which I personally would like to
see in the documentation. It is by no means complete and i can resend it
to this list if necessary. The documentation should be provided in the
HTML format (I think so anyways), just because most of the people
are familiar with it. Providing a good template for the web page is
essential.
NOTE: Some people may argue that HTML is not a best format and I
agree, so personally I do not care about the format per se, except that
the only requirement is that there are tools to convert that format to
HTML.
Now, there are a bunch of freeware tools out there to convert
HTML to a number of different formats. My thoughts on the matter are:
- use HTML as a base and reference on the website
- provide a single converted PostScript and PDF docs
-this is useful for downloading and printing whole docs
- provide .HLP files via HTML->RTF converter.
- then all we need is some .HPJ files and we got windows docs.
Additional format maybe added later on if people are requesting them, but
the above should be bare minimum.
Regarding general setup
- every page should have a link to searchable contents
- multiple cross-referencing of topics
- table of contents
- tools (distributed with docs) to automatically
regenerate documentations.
- some form of style guide for writing the docs
Plan:
- everyone come up with a single page setup and put it on some
web page where people can try it out and pick the best one.
- negotiate a table of contents
- write tools for automatic generation of docs
- write docs
- ideally this would be a multicycle process, where
an "editor(s)" check contents before approval.
- due to the everchanging nature of the server, it would
be futile to write docs on new stuff, therefore we should
start with stable (unlikely to change) topics, like :
- CGI, SSI, etc.
I got some inspiring ideas of documentation for commercial webservers, so
if you have time, take a look at :
http://www.roxen.com/documentation/manuals/challenger/
http://website.ora.com/wspro/wsapi/html/
http://www.aolserver.com/server/docs/2.0/html/
All opinions are my own and you are free to disagree with them.
Stanley.
