From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,88ed72d98e6b3457 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2003-10-29 15:34:11 PST Path: archiver1.google.com!news1.google.com!newsfeed.stanford.edu!logbridge.uoregon.edu!newshub.sdsu.edu!elnk-nf2-pas!newsfeed.earthlink.net!stamper.news.pas.earthlink.net!stamper.news.atl.earthlink.net!newsread1.news.atl.earthlink.net.POSTED!d9c68f36!not-for-mail Message-ID: <3FA04E6E.2070000@noplace.com> From: Marin David Condic User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.0.1) Gecko/20020823 Netscape/7.0 (OEM-HPQ-PRS1C03) X-Accept-Language: en-us, en MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Standard Library Interest? (The Big Player ACT) References: <3F7F760E.2020901@comcast.net> <3F81FBEC.9010103@noplace.com><6Ingb.30667$541.13861@nwrdny02.gnilink.net><3F82B4A4.5060301@noplace.com><3F82F527.3020101@noplace.com> <3F9EFDC6.7050508@noplace.com> <254c16a.0310290635.1a8b09d2@posting.google.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Date: Wed, 29 Oct 2003 23:34:09 GMT NNTP-Posting-Host: 209.165.29.47 X-Complaints-To: abuse@earthlink.net X-Trace: newsread1.news.atl.earthlink.net 1067470449 209.165.29.47 (Wed, 29 Oct 2003 15:34:09 PST) NNTP-Posting-Date: Wed, 29 Oct 2003 15:34:09 PST Organization: EarthLink Inc. -- http://www.EarthLink.net Xref: archiver1.google.com comp.lang.ada:1832 Date: 2003-10-29T23:34:09+00:00 List-Id: 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 ======================================================================