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