I haven't struck those things previously .... having a look now. Certainly looks like a vast improvement on the previous awful offerings.
As for suggestions ... employ the most junior person in the team to write docs rather than the most experienced !!!! The basic problem with virtually ALL technical documentation is that by conventioni its written by someone EXTREMELY experienced. This practice guarantees that countless minor but critical steps will be glossed over. I wish someone would recognize that one of the main reasons why Microsoft & the Dummies books are so successful in the "real world" (despite their many shortcomings in many areas) .... its simply that the stuff is usable NOW by regular folks who don't have the time to sit down and wade through hundreds of pages of verbiage to get the answer to something which could have been answered in two lines. The reason I changed all the servers I admin from linux to FreeBSD is simply that the O/S is infinitely more logical, allowing me to prepare my own user documentation that regular users (as opposed to highly experienced geeks) can comprehend. ----- Original Message ----- From: "Joshua Slive" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Wednesday, September 27, 2000 7:53 AM Subject: Re: Apache Documentation] > On Wed, 27 Sep 2000, Doug Young wrote: > > > This is EXACTLY the problem faced by most regular (as in non geeky) users > > of apache. There's no question that apache itself usually performs well, but > > trying to make sense of the horribly obtuse documentation is a real feat. > > I've prepared a basic tutorial on FreeBSD setup / configuration for the > > thousand > > odd members of a non-profit internet access group & have received countless > > comments along the lines that "its nice to see that someone has finally > > prepared > > some docs in regular user language". I would like to do something similar on > > apache, > > but to do so one needs to find simple english answers in the first place ... > > the present > > state of the "official" docs is such that apache.org is the LAST place for > > regular users > > to go in search of intelligible answers !!!! > > > > Check the recently added: > http://www.apache.org/docs/misc/tutorials.html > > I actually think that the apache docs are not that bad. However, they are > a "reference" and not a "guide". You need to already know something about > what you want to do before the docs will help you do it. I think they > were basically written from the perspective of an experieced web admin > upgrading from NCSA httpd. > > So, do you have specific suggestions? > > -- > Joshua Slive > [EMAIL PROTECTED] > http://finance.commerce.ubc.ca/~slive/ > Phone: (604) 822-1871 >
