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

[Jeremy Madea <J....@mdl.com>]

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

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

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

David orginally commented:
> > 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.
>
To which Jeremy replied:
> Rather than continue this discussion, which is off-topic
and of little value
> to anyone,

And David interjects:
Obviously not to those who do not share your perspective --
I trust my correspondence shows more respect for your
opinion than you do of mine.

And Jeremy continues:
>I suggest that you dedicate your keystrokes to improving
the
> documentation in those areas where you find it deficient.
Maybe you can
> help.

And David further interjects:

Your suggestion was previously anticipated - perhaps you
might care to respond thoughfully  to the suggestion I made
at 10:43 a.m. -- some three hours before the email to which
I am replying.

Before Jeremy's further continuance:
> Your writing isn't half-bad;

Which earns another interjection from David:
If I was a little younger and more volatile I might have
take an opportunity to refer you to some respected works on
the art of polite condescension -- but

And Jeremy wags a finger while saying:
> it might even be good if you learn to
> curb your prolixity.

David concludes by saying:
as it is a free country I guess you are entitled to display,
as you choose, your own level of respect for others and
their opinions when they do not coincide with your own.

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