documentation suggestions

[Joshua Slive <jo...@slive.ca>]

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.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: documentation suggestions

[Mark Constable <ma...@renta.net>]

On Tue, 1 Jan 2002 05:18, Joshua Slive wrote:

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

That sounds like a Wiki to me :) If I may indulge... a minimal
breakdown is guidance for total newbies who just want to run
apache for the first time on a linux (ie; un*x-like) system
where they have to deal with two new concepts at the same time,
linuxisms and apache. The other, more complex case, is outlining
how various systems, including professional vhosting, can be setup
and operated. I know there are many more potential setup options
but breaking it down into at least these two avoid dumping complex
answers in newbies faces, and allows experienced people to skip
over some endless dribble they already know about.

Again, documentation incubation could be broken down into two
fundamental levels: various informal input methods, anything
that makes it easy to gather informative seeds, and, the more
traditional permanent docu pages we are all familiar with (that
also evolve over time) that have tougher input rules.

My new found enthusiasm for Wikis is because they have the least
resistance to creating web based content that I am aware of, no
contest... anyone can add content to a page and create a whole
new page just by spontaneously typing in stream-of-consciousness
mode with minimal effort. The most powerful potential is that
_anyone_ can "refactor" a page at anytime, that is, take it upon
them self to re-edit the page and sift out cruft and present the
concepts therein in a clearer sequence. Every other system I am
aware of requires varying degrees of startup formality before
being able to contribute to a work/mind-flow. Wikis are almost
bizarre in their lack of such formalities, so open in fact that
I find the principal simply baffles people... even me, and I'm
an enthusiast.

I'm not suggesting apache.org should adopt a Wiki as there are
security and abuse issues involved but a web-ringish set of Wikis
and faqomatics and even plain pages by independent enthusiasts
could be useful to seed further evolvement of the canonical
httpd.apache.org docset... especially if formally encouraged.

Now, what the httpd.apache.org very definitely could do with is
adopting the php.net/manual concept of allowing focussed user
contributions on every manual page. That system is absolutely
brilliant and I'm at a loss to understand why it's not more
universally adopted by other projects. Perhaps it's spinoff of
the ease-of-use and mind set of PHP users that makes it feasible.
Fully 1/2 the value (to me) of that doc system is what other
users have contributed (particularly examples) over the last
year or so.

Summary... beyond the expected reference docs, clearly divide
howto/faqs/examples into beginners and advanced sections.
Consider an informal seeding and nurturing of future formal
documentation as a natural part of the process, and encourage
it... ie; don't make the mistake of requiring SGML/Docbook
expertise before jo-user is able to contribute to the
documentation flow.

Oh, and dare I mention "example configs"... and lots of them.

--markc

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

Re: documentation suggestions

[Irmund Thum <it...@it97.dyn.dhs.org>]

Mark Constable wrote:
> 
> Now, what the httpd.apache.org very definitely could do with is
> adopting the php.net/manual concept of allowing focussed user
> contributions on every manual page. That system is absolutely
> brilliant and I'm at a loss to understand why it's not more
> universally adopted by other projects. Perhaps it's spinoff of
> the ease-of-use and mind set of PHP users that makes it feasible.
> Fully 1/2 the value (to me) of that doc system is what other
> users have contributed (particularly examples) over the last
> year or so.
> 

I totally agree!
Let me give an example:
using the squid proxy over all the years I've just decided to have a
look into Apache's proxy module since I may have more Windoz customers
this year who can live with that cache - and it's not all that exciting
to install cygwin and running squid on a win box, works, was tested,
some problems with Wins (DNS).
Looking into the doc for mod_proxy I was really missing something like
on the php-sites,
examples of users, how they experience this module.
Even I wasn't sure for some minutes what port I should/can use
(use your webbrowser's search function looking for port on the site <:).
the best configuration examples finally I've found within my Apache book
(Lars Eilebrecht)
But not everybody has in every situation a good book in the hand :-
the idea of letting Apache users adding comments like on the php-site is
simply great!
-- 
_ ___
|  |  Irmund    Thum
|  |

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

Re: documentation suggestions

[David Morsberger <da...@home.com>]

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" <jo...@slive.ca>
> Reply-To: users@httpd.apache.org
> Date: Mon, 31 Dec 2001 14:18:58 -0500
> To: <us...@httpd.apache.org>
> Cc: <do...@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