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

[Marin David Condic <nobody@noplace.com>]

Yes. Yeah Verrily! And well said.

A good example of library documentation is what you get with the MFC in 
MSVC++. O.K. we could stand here and pick on it for hours (and probably 
will, now that I've made the bold claim that Microsoft did something 
well. ;-) Compared to what you see with most other freebie stuff you get 
from the Internet, the MS documentation of the MFC is light-years ahead 
of anything else. I just downloaded a library of Ada stuff that I don't 
wish to criticize, so I won't name it, but upon inspection, all that was 
in the distro was the source code and the license. So what you get is 
whatever comments are in the code and whatever info you may have gleaned 
from the website. That's a far cry from a hyperlinked document that is 
integrated with the IDE for point-n-click info on any MFC class.

The thing is that it is *HARD* and *TIME CONSUMING* to produce a really 
good document and as soon as a library moves beyond something trivial, 
your average volunteer enthusiast is going to lose interest in spending 
the necessary time to get it right.

That's why I've been suggesting that to get a good, Conventional Ada 
Library of some sort that is used on most Ada platforms, its going to 
take more than just some volunteers hacking some stuff together and 
putting it on a web site. Even if that was just "a start" with the hope 
that one day, the vendors would pick it up and build on it and turn it 
into "The Standard", it has a whole lot of speculation and "ifs" to 
overcome. I don't think it would work without some committment of 
support and guidance from the vendors. It almost has to have some kind 
of "for-profit" motive built into it or its just too big an undertaking 
to happen on its own.

MDC


Marc A. Criley wrote:
> 
> 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"


-- 
======================================================================
Marin David Condic
I work for: http://www.belcan.com/
My project is: http://www.jsf.mil/NSFrames.htm

Send Replies To: m   o   d   c @ a   m   o   g
                    c   n   i       c   .   r

     "So if I understand 'The Matrix Reloaded' correctly, the Matrix is
     basically a Microsoft operating system - it runs for a while and
     then crashes and reboots. By design, no less. Neo is just a
     memory leak that's too hard to fix, so they left him in... The
     users don't complain because they're packed in slush and kept
     sedated"

         --  Marin D. Condic
======================================================================