httpd-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Joshua Slive" <jos...@slive.ca>
Subject documentation suggestions
Date Mon, 31 Dec 2001 19:18:58 GMT
By the way, let me make something clear:

I know I can sometimes seem little defensive when it comes to documentation
changes.  I do very much appreciate suggestions.  If you really want to
help, the right place is the documentation project:
http://httpd.apache.org/docs-project/ but you should feel free to continue
sending suggestions here if you want.

But writing a good set of docs is harder than it seems.  Everybody who
configures apache has some little thing that it took them ages to figure
out, and they say "gee, I wish that was in the docs".  That is quite
reasonable, but you must understand that apache is used for so many
different things by so many different people, that we can't really write
docs this way.  We would wind up with just a huge list of "how to do this,
how to do that, how to do some other thing".  This would be confusing to
read and impossible to manage.

Instead, my goal for the docs is to clearly describe how the server works in
general, with some examples to clarify how to do things.  Then people can
(hopefully) build more complicated configurations by using what they learn.

Now, that is not to say that a huge list of "How-to" type documentation is a
bad idea.  I think it would be great to have something like this that could
be managed separately from the docs.  Even better would be to make it a
community project of the faq-o-matic/wiki/whatever type.  That sort of thing
has been suggested before, but we've never put the time into getting it
going.

Some of the keys to making that work are: A good piece of software that
allows people to easily make additions, but still allows some editorial
control to weed out the inevitable garbage; A sufficiently large community
behind it.

Joshua.


---------------------------------------------------------------------
The official User-To-User support forum of the Apache HTTP Server Project.
See <URL:http://httpd.apache.org/userslist.html> for more info.
To unsubscribe, e-mail: users-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org


Mime
View raw message