httpd-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "vizion communication" <viz...@ixpres.com>
Subject Re: [users@httpd] level of docs (was Re: [users@httpd] Error Logs)
Date Thu, 08 May 2003 14:59:25 GMT

>>>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" <joshua@slive.ca>
To: <users@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


Mime
View raw message