Mailing List Archive

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

I realize there's a "Dummies" book on the subject .... these used to be
popular in OZ
a few years back, but with the all time low value of the local currency
relative to the
$US they are becoming too expensive for many. Pity someone in Europe hasn't
produced something in print .... at least the eu is still compatible with
the $OZ

----- Original Message -----
From: "Rodent of Unusual Size" <Ken.Coar@Golux.Com>
To: "Apache docs list" <apache-docs@apache.org>
Sent: Wednesday, September 27, 2000 3:27 AM
Subject: [Fwd: Apache Documentation]


> Some remarks from a docco user from a couple of years ago..
> FWIW.
> --
> #ken P-)}
>
> Ken Coar <http://Golux.Com/coar/>
> Apache Software Foundation <http://www.apache.org/>
> "Apache Server for Dummies" <http://Apache-Server.Com/>
> "Apache Server Unleashed" <http://ApacheUnleashed.Com/>

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

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
>

That tutorial link is definitely a step in the right direction ...
at least some of the pages have something like the proper
"step by step" format that us regular folk have been asking
for since the dawn of time.


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