httpd-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeremy Madea <J.Ma...@mdl.com>
Subject RE: [users@httpd] level of docs (was Re: [users@httpd] Error Logs )
Date Thu, 08 May 2003 18:51:46 GMT
On Thursday, May 08, 2003 7:59 AM, vizion communication wrote:

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

You do realize that the Apache project is a volunteer effort, don't you? 


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

No matter how well the manual is written, there will always be people that
don't understand it. Some of them would if they only devoted a bit more
effort. Some of them simply need active instruction. Some of them will never
understand it at all. 


> The effective
> manual is one that closes the knowledge gap between the
> reader and the task that the reader needs to address.

An effective manual is one that provides the necessary information in an
accessible format to the majority of readers. An effective -reader- closes
his own knowledge gaps (and probably uses a manual as only one of several
tools to do that.) 
 

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

This is natural and good. It isn't reasonable to expect the writers to try
to "close the knowledge gap between the reader and the task that the reader
needs to address." The writers have no idea what that task is! Usually,
there are as many such tasks as there are readers. Or more. It is the
responsibility of the documentation author to present information and it is
the responsibility of the user to apply that information as necessary. 


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

On a list such as this, you will -always- see questions recurring even when
they are very succinctly addressed in supporting documentation. What you
don't see is that, for each time someone asks a FAQ on the list, many people
with the same question successfully find enough information in the docs to
answer it for themselves.


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

Rather than continue this discussion, which is off-topic and of little value
to anyone, I suggest that you dedicate your keystrokes to improving the
documentation in those areas where you find it deficient. Maybe you can
help. Your writing isn't half-bad; it might even be good if you learn to
curb your prolixity.  

-j

--
Jeremy Madea
"My two cents aren't worth a dime."


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