[users@httpd] level of docs (was Re: [users@httpd] Error Logs)

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

On Wed, 7 May 2003, vizion communication wrote:

> Although I have been using apache for years I agree...
>
> Doc writing is a highly specialized skill - and it requires
> of people that write the docs to know what they are writing
> about but, in the course of writing, to assume the reader
> knows nothing!!!

Although parts of what you say are true (it is important to try to put
yourself in the perspective of the reader/questioner), this particular
statement is bullshit.

All docs assume a base level of knowledge: Fix-it books do not describe
how to use a screwdriver, and 747 flight manuals do not define the concept
of an airport.  The trick is not to assume the reader knows nothing, but
rather to write at the appropriate level for your target audience.

In the case of the apache docs, this is almost impossible, since the
target audience ranges from the ultra-expert to the guy who just figured
out how to boot win98 and now wants a web server (errr, something to
point his browser at...).  The apache docs tend to lean more towards the
former for two main reasons: 1) they are written mostly by programmers;
and 2) it takes much less time to write expert docs than beginner docs,
and time is always at a premium with open source projects.

Given that, I have three more useful comments:

1) Yes, people on this list should try to take into account that fact that
the docs do not answer everyones needs.  I tend to start by pointing
people to the docs (usually a very specific doc, not just the homepage),
but I am happy to elaborate if they return and say "I don't understand
that."

2) There are many resource available for novices who have problems with
the docs.  For example, many apache books are targeted at beginners.

3) If you think the docs need improvement (and indeed they always do),
please come on over:
http://httpd.apache.org/docs-project/

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
   "   from the digest: users-digest-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org

Re: [users@httpd] level of docs (was: [users@httpd] level of docs

[André Malo <nd...@perlig.de>]

* vizion communication wrote:

<snip>

You're basically right. The docs needs of course more user oriented
documentation. But

> I would like to add some detailed suggestions and illustrate
> my observations as soon as I get a chance - but right now I
> need to attend to some other stuff.

that is nearly always the problem. I know a lot of people who would help -
if they had the time. Mostly they lose their interest later and that's it.
Just talking about "why is must be done better" doesn't help.

I'm repeating Joshua's offer: join the docs-project and point out specific
things that can be improved and how it could be done. You do not need to
actual write documentation (though it would be cool if you did ;-).
That's not meant as an offense or bucket-passing. It's really serious. We
*do* need people who are able to get the user's point of view and are able
to explain the user problems to the too-much-involved people.
(simple spoken)

nd
-- 
s;.*;aaaaaoaaaoaaaaooooaaoaaaomaaaa:a:alataa:aaoat:a:a:a
maoaa:a:laoata:a:oia:a:o:a:m:a:o:alaoooat:aaool:aaoaa
matooololaaatoto:aaa:o:a:o:m;;s:\s:\::g;y;mailto:;
\40\51/\134\137|ndparker <nd...@perlig.de>;;print;

---------------------------------------------------------------------
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
   "   from the digest: users-digest-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org

Re: [users@httpd] level of docs (was Re: [users@httpd] Error Logs)

[vizion communication <vi...@ixpres.com>]

>>>This is wrong, and in fact, insulting to the many people
who >>>have created
>>>what I consider to be a very above-average set of docs.
I need to say the manuals are above average but those does
not necessarily mean they cannot be improved----

If you >>>think you
>>>can do better, then what is stopping you?

It seems to be a way of saying -  you are charity cases --
do not dare criticise unless you are doing it -- your
opinions/judgements are irrelevant. It seems to be saying
"Only say something if you share our viewpoint". I do not
see this as a helpful or encouraging response. I would
prefer someone to say -- I think we hear you -- let me see
if I understand you correctly.

Come on this is useful stuff - we need to acknowledge that
when those who are incolved in writing the manuals sounding
off at people who say for, what appears to me to be, very
good reason that they do not understand something in the
manual then I feel it is time to take stock and ask how the
job could be done better.. otherwise the cycle continues.

My observation is that the issue is systemic rather than due
to isolated examples and the systemic problem is one that is
faced by all professional manual writers. The effective
manual is one that closes the knowledge gap between the
reader and the task that the reader needs to address.

Readers of manuals digest them for a purpose --their primary
purpose is to use the software in the course of which they
get to understand the bits they need to use.

The danger is that without a disciplined approach manual
writers tend to drift towards trying to close the knowledge
gap between the writer and the reader! By doing this they
can, without realizing it, finish up producing something
that fails the readership who really need the manual!!

If topics repeatedly come up on this list --and they do -
then the chances are that topic is, for one reason or
another, not effectively handled in the manual from the
user's perspective.

My view is the problems I will identify are due less to a
lack of material within the documentation but more to a lack
of understanding by the writers about how to present the
information in a form and manner that makes it  really
useful for the purpose of the user.

To the extent that a manual does not serve the newuser
effectively it is to that extent deficient. Now I know the
absence of an effective manual creates a good market place
for a book on the subject -- but surely the manual should be
better than a third party book!!!

I would like to add some detailed suggestions and illustrate
my observations as soon as I get a chance - but right now I
need to attend to some other stuff.

Let us keep this going on the basis that there is no
intention by anyone to insult or belittle the work that is
done -- only a desire by people of goodwill to constantly
improve what is available and this dialogue, to my mind,
forms part of that process.

David




----- Original Message -----
From: "Joshua Slive" <jo...@slive.ca>
To: <us...@httpd.apache.org>
Sent: Thursday, May 08, 2003 7:09 AM
Subject: Re: [users@httpd] level of docs (was Re:
[users@httpd] Error Logs)


>
> [As someone else has mentioned, this is only semi-on-topic
for this list;
> but since I enjoy arguing about this stuff...]
>
>
> On Wed, 7 May 2003, vizion communication wrote:
> > The apache docs tend to lean
> > more towards the
> > > former for two main reasons: 1) they are written
mostly by
> > programmers;
>
> > Unfortunately that is a bad choice
>
> Who said anything about a choice?  I stated a fact.
Non-programmers who
> want to participate are welcome (as is explicitly stated
on the docs
> page).
>
> > So many questions which arise on
> > this list would mot arise if the documentation was more
> > professionally written by those who are able to assume a
> > greater level of ignorance OR took time to identify
> > assumptions that are being made and to point the reader
to a
> > document that SIMPLY fills the knowledge gap.
>
> x> 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
>    "   from the digest:
users-digest-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
   "   from the digest: users-digest-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org

Re: [users@httpd] level of docs (was Re: [users@httpd] Error Logs)

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

[As someone else has mentioned, this is only semi-on-topic for this list;
but since I enjoy arguing about this stuff...]


On Wed, 7 May 2003, vizion communication wrote:
> The apache docs tend to lean
> more towards the
> > former for two main reasons: 1) they are written mostly by
> programmers;

> Unfortunately that is a bad choice

Who said anything about a choice?  I stated a fact.  Non-programmers who
want to participate are welcome (as is explicitly stated on the docs
page).

> So many questions which arise on
> this list would mot arise if the documentation was more
> professionally written by those who are able to assume a
> greater level of ignorance OR took time to identify
> assumptions that are being made and to point the reader to a
> document that SIMPLY fills the knowledge gap.

This is wrong, and in fact, insulting to the many people who have created
what I consider to be a very above-average set of docs.  If you think you
can do better, then what is stopping you?

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
   "   from the digest: users-digest-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org

Re: [users@httpd] level of docs (was Re: [users@httpd] Error Logs)

[vizion communication <vi...@ixpres.com>]

----- Original Message -----
From: "Joshua Slive" <jo...@slive.ca>
To: <us...@httpd.apache.org>
Sent: Wednesday, May 07, 2003 7:05 AM
Subject: [users@httpd] level of docs (was Re: [users@httpd]
Error Logs)


>
> On Wed, 7 May 2003, vizion communication wrote:
>
> Although parts of what you say are true (it is important
to try to put
> yourself in the perspective of the reader/questioner),
this particular
> statement is bullshit.

One of my mentors told me that when there is resort to
invective then offer someone the use of a compost bin so
that something useful comes out of the process...
>

>
> In the case of the apache docs, this is almost impossible,
since the
> target audience ranges from the ultra-expert to the guy
who just figured
> out how to boot win98 and now wants a web server (errr,
something to
> point his browser at...).  The apache docs tend to lean
more towards the
> former for two main reasons: 1) they are written mostly by
programmers;
Unfortunately that is a bad choice -- to get those who know
far too much about oo little to write documents for those
who know too little about too much is a sure recipe for
waste of time and resouces. So many questions which arise on
this list would mot arise if the documentation was more
professionally written by those who are able to assume a
greater level of ignorance OR took time to identify
assumptions that are being made and to point the reader to a
document that SIMPLY fills the knowledge gap. Unti that
happens we must bve grateful to those who have taken the
trouble to suppl what is availble. At the same time I hate
to see people being chastized for "not having read the
manual -- rather than a response which says -- humph well
the manual says this but I can see that you need to also
know "this" if you are going to be able to make use of
it.!!!

> and 2) it takes much less time to write expert docs than
beginner docs,
THis means it gets reviewed by peers who also have an
insufficient level of ignorance to provide the feed back
that is needed... so the manual writer does not get the
level of critique that is really needed to raise the quality
of the manual to the point where it does satisfy a target
audience that really does need a manual!!! In consequence
there is areal danger of getting a manual written for a
target audience that do not need one and can sort out what
they need to do by looking at the source code!!!

David





---------------------------------------------------------------------
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
   "   from the digest: users-digest-unsubscribe@httpd.apache.org
For additional commands, e-mail: users-help@httpd.apache.org