Ron Parker wrote:
> 
> On Tue, 21 Sep 1999 01:25:55 -0700, Ken wrote:
> >  When a new patch comes out however the writer of the patch is inundated
> >with questions from the users of the patch seeking clarification on
> >operating parameters and ideologies behind the function of the patch.
> >One would think that the patch writers would try to head off all of the
> >questions they are eventually going to have to field anyway by spending a
> >few minutes documenting their new labor of love.
> 
> I think part of it is psychological.  When we're writing documentation,
> we're not writing for anyone in particular, and it's easy to think that
> nobody will ever actually read it.

A poor asumption I can assure you :)

>  When we're answering questions in the
> newsgroups or by email, there's actually a specific recipient - someone
> who will definitely read the response - so it doesn't feel so much like
> wasted effort.

Immediate gratification not withstanding documentation efforts are seldom
wasted time.

> Also, there's the fact that when we're answering a specific question, it's
> probably only about a single facet of the whole thing, so it's a much less
> overwhelming task than documenting the whole thing at one go.  This is
> especially true of complex patches with no well-defined purpose, like UVpov
> or the isosurface patch, or of huge patches like the Superpatch (which I've
> opted to "document" by including the original docs for each patch, sparse
> though they may be.)

  As an engineer I have had the task of working on several documentation
projects. I agree that it can be a daunting task and if you want a real
good time try to do it sometime for a mil spec application -- OUCH !
For other types of documentation like for POV-Ray patches I would think
it would almost be fun in comparison. Oh well as you say human nature is
a beast and we are all guilty at not fulfilling our obligations from
time to time.
 Is a lack of documentation grounds for erroneous bug reports due to lack
of understanding on the part of the user ? Look at the posting history in
the bug reports group... :)

-- 
Ken Tyler

See my 1000+ Povray and 3D Rendering and Raytracing Links at:
http://home.pacbell.net/tylereng/index.html

Post a reply to this message