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,cec04f9d45b3f527 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2003-09-01 18:10:16 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!not-for-mail Message-ID: <3F53EDE8.6090908@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: An Ada advocacy method References: <3F4F4817.7030306@noplace.com> <3F50130A.1070406@noplace.com> <3F50A70E.7050809@noplace.com> <3F521B65.1090004@noplace.com> <20030831123103.43926d87.falis@verizon.net> <3F535639.9060008@noplace.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Date: Tue, 02 Sep 2003 01:10:15 GMT NNTP-Posting-Host: 209.165.27.210 X-Complaints-To: abuse@earthlink.net X-Trace: newsread1.news.atl.earthlink.net 1062465015 209.165.27.210 (Mon, 01 Sep 2003 18:10:15 PDT) NNTP-Posting-Date: Mon, 01 Sep 2003 18:10:15 PDT Organization: EarthLink Inc. -- http://www.EarthLink.net Xref: archiver1.google.com comp.lang.ada:42050 Date: 2003-09-02T01:10:15+00:00 List-Id: Documentation can only be as good as the writer. Let's put this in perspective. Take your average program in your average editor and highlight some system provided subroutine and hit the "Help" key. If you got nothing, that's pretty typical and usually pretty useless. If you got a single sentence saying "This is the gazorenthorpe subroutine", you got something close to useless. If it gave you a page that described what the subroutine is supposed to do and what the parameters are supposed to be and maybe an example or two of proper usage and perhaps some links to similar or related subroutines, you got something that is a damned sight better than "nothing" or a single sentence. Microsoft may not have written Shakespearian quality documentation, but in my book, something more than "nothing" is pretty nice to have. In all my usage of MSVC++ and my many trips into the documentation, I usually could find out what the average programmer needed to know in order to use some provided feature and that's a reasonable definition of "thorough" so far as I can tell. MDC Wes Groleau wrote: > > Define thorough. If it's like most Microsoft documentation, > it means lots of words in lots of files, but it does not mean > something one can actually get any assistance from. > > Apple's online help is just as useful as Microsoft's. But > at least they don't try to hide the fact by making it LOOK > like an encyclopedia. > > (I am not trying to claim that Ada has anything better!) > -- ====================================================================== Marin David Condic I work for: http://www.belcan.com/ My project is: http://www.jast.mil/ Send Replies To: m c o n d i c @ a c m . o r g "In general the art of government consists in taking as much money as possible from one class of citizens to give to the other." -- Voltaire ======================================================================