From: Chad Perrin <perrin@...>
Date: 2007-07-16T07:42:25+09:00
Subject: Re: graphing/charting application

On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:
> In message <20070715212911.GC18755@demeter.hydra>, Chad Perrin writes:
> >RDoc were written specifically to ease the process of creating
> >documentation, to provide a solid beginning to that documentation so that
> >half the work is already done for someone that intimately knows the
> >software, but the end result is that many people seem to think that *is*
> >the documentation and never bother finishing the job.  Documentation is
> >an important part of any development effort -- almost as important as the
> >software itself.  Documentation is important for the same reason readable
> >code is important, and yet people who will argue for days on end about
> >the best way to eke that last bit of readability out of code will turn
> >around and go on producing software without even the most rudimentary
> >attempt to make documentation clear and useful.
> 
> I think many developers underestimate the significance of documentation
> to projects.  Of course, most of us have at least some practice figuring
> things out without documentation, reading source, and so on...

True.  It's a shame that there isn't better documentation for some
projects, however -- especially since that often means someone will go
use something else (with better documentation) instead.  While I could
eventually puzzle out how to use Gruff effectively, for instance, I'd
rather have something with good documentation at my fingertips than have
to pore over source code just for a trivial use of the library.

Since I've been accused of something akin to solipsism before in this
discussion, I'll be clear: I'm not saying that I, personally, am an
important user to whom developers must cater.  Read my personal
experience as a symptom of a deeper problem with the lack of quality
documentation, please.


> 
> But putting in a few years as a writer leaves me more concerned with
> documentation than I used to be.  I'll say that much.

Writing what amounts to tutorial documentation for money in the last few
years has certainly improved my understanding of the importance of
documentation -- but I think the biggest change to my perspective is in
the fact that I'm using libraries much more these days than I used to,
and thus finding poor library documentation far more problematic than I
used to.

-- 
CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
Marvin Minsky: "It's just incredible that a trillion-synapse computer could
actually spend Saturday afternoon watching a football game."