Re: Standard Library Interest? (The Big Player ACT)

[mcq95@earthlink.net (Marc A. Criley)]

Marin David Condic <nobody@noplace.com> wrote in message news:<3F9EFDC6.7050508@noplace.com>...
> So I feel a little vindicated.

Yep!

> Here we have a vendor saying that they 
> wouldnt' want something that was just slapped together from odds and 
> ends collected from the Internet. They need something consistent and 
> well documented. In all likelihood, ACT would not be unique in this respect.

The part I want to focus on is ACT's repeated insistence on good
quality documentation, as Stephane reported back from his conversation
with ACT.  I completely understand where they're coming from, and
agree with that position.  What passes for documentation with many
open-source/spare-time developed products is barely more than the
usage notes the developer happened to write down while the code was
being written.

It takes a lot of work to write useful documentation, stuff that goes
beyond:
    Flags:       The flags associated with the I/O operation.

It took weeks of spare time to write and edit the DTraq User Manual
(http://www.mckae.com/dtq_common/DTraq.pdf), which involved repeatedly
submitting updates and rework to an editor that vigorously checked it
for readability, usability, accuracy, and clarity.  (My
wife...er...editor, is in the same line of work as I am and so has
also struggled with the deficiencies of documentation, of both open
source and proprietary products.)

I can't begin to tell you how frustrating it is to try to use an
application or tool or utility that looks and sounds really good, but
then have to spend hours trying to figure out how to use it more
effectively than what's given in the single accompanying 5-step
example.  I end up scouring the Web for tutorials, such as for Xerces,
or grepping source code.

Examples are nice, but examples are supposed to illustrate what the
documentation is conveying, not _be_ the documentation.

Without the commitment to provide (and maintain!) good documentation,
the users of a product (or tool or library) will get frustrated,
perhaps even to the point of discarding it because it's just too hard
to figure out how to use.  Obviously ACT, as a for-profit business,
has no time to waste on under-documented products, and simply
eliminates them from consideration on the spot.  It may seem unfair
and shortsighted to the developer, but ACT (and other businesses) have
to worry about the costs, and trying to figure out how your product
works by grepping source code is just not an efficient way to do that.

Marc A. Criley
mc NOSPAM @ mckae.com  -- You know what to do...
McKaeTechnologies
"The Efficient Production of High Quality Software"