httpd-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Morsberger <davidmorsber...@home.com>
Subject Re: documentation suggestions
Date Mon, 31 Dec 2001 20:37:50 GMT
Joshua,

I understand the desire for a reference guide but what is missing is a
document that discusses the overall interaction of the directives. There may
exist one but I am not aware of it.

For example, 

The Option directive can occur within nested directives. What is the
relationship between them?

How does the VirtualHost directive effect the DocumentRoot directive? From
trial and error I deduced that the the DoucmentRoot directory my be defined
within a VirtualHost directive.

Is there a tree-like view that presents the relationship / interaction
between the directives?

What question do I think needs to be answered?

 - How do I configure on host X? No, this is covered in the installation
guides / readmes.

 - What does directive Y do? This is covered in the current documents.

 - What happens when a http request is received? A brief thread through the
system. It is always easier to setup a directive when you know how it fits
in to the overall picture.

Does anyone else have a specific question that if answered (in a concise
manner) would make the newbie's life easier?
 
Who is the audience? It needs to be a system administrator with minimal
programming experience. The software will give the SA their requirements and
the software engineers will use the infrastructure the SA sets up.


> From: "Joshua Slive" <joshua@slive.ca>
> Reply-To: users@httpd.apache.org
> Date: Mon, 31 Dec 2001 14:18:58 -0500
> To: <users@httpd.apache.org>
> Cc: <docs@httpd.apache.org>
> Subject: documentation suggestions
> 
> 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
> 


---------------------------------------------------------------------
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