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 06:35:35 PST Path: archiver1.google.com!postnews1.google.com!not-for-mail From: mcq95@earthlink.net (Marc A. Criley) Newsgroups: comp.lang.ada Subject: Re: Standard Library Interest? (The Big Player ACT) Date: 29 Oct 2003 06:35:34 -0800 Organization: http://groups.google.com Message-ID: <254c16a.0310290635.1a8b09d2@posting.google.com> 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> NNTP-Posting-Host: 69.73.18.83 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit X-Trace: posting.google.com 1067438134 30809 127.0.0.1 (29 Oct 2003 14:35:34 GMT) X-Complaints-To: groups-abuse@google.com NNTP-Posting-Date: Wed, 29 Oct 2003 14:35:34 +0000 (UTC) Xref: archiver1.google.com comp.lang.ada:1808 Date: 2003-10-29T06:35:34-08:00 List-Id: Marin David Condic 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"