Re: List maintenance item

From: Stanley Gambarin <stanleyg(at)cs.bu.edu>
Date: Thu Aug 07 1997 - 16:42:00 EDT

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.

Received on Thu Aug 7 13:42:15 1997