httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Doug Young" <do...@gargoyle.apana.org.au>
Subject Re: Apache Documentation]
Date Tue, 26 Sep 2000 22:18:51 GMT
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" <slive@finance.commerce.ubc.ca>
To: <apache-docs@apache.org>
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
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871
>


Mime
View raw message