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=-0.3 required=5.0 tests=BAYES_00, REPLYTO_WITHOUT_TO_CC autolearn=no 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:58:14 PST Path: archiver1.google.com!news1.google.com!newsfeed.stanford.edu!headwall.stanford.edu!newshub.sdsu.edu!small1.nntp.aus1.giganews.com!border1.nntp.aus1.giganews.com!intern1.nntp.aus1.giganews.com!nntp.giganews.com!nntp.gbronline.com!news.gbronline.com.POSTED!not-for-mail NNTP-Posting-Date: Mon, 01 Sep 2003 20:58:12 -0500 Date: Mon, 01 Sep 2003 20:59:20 -0500 From: Wes Groleau Reply-To: groleau@freeshell.org Organization: Ain't no organization here! User-Agent: Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.4) Gecko/20030624 X-Accept-Language: en-us, en, es-mx, pt-br, fr-ca MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Online help (was: 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> <3F53EDE8.6090908@noplace.com> In-Reply-To: <3F53EDE8.6090908@noplace.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Message-ID: NNTP-Posting-Host: 69.9.86.117 X-Trace: sv3-UuviBurY+eeLITbfHqhP1daBU8cwnZkknbbz2qxeuiP6OGZk2ValExJHEqowLXIKZ/VkZG1D8/OoTJX!7wSnjVi6tcuLidJZd8aTzYmty/ZYUgUUydwi86h3HVbdrdFbLt/6lDXVzyS7DstTm5yh6rq3KL1m!Tw== X-Complaints-To: abuse@gbronline.com X-DMCA-Complaints-To: abuse@gbronline.com X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.1 Xref: archiver1.google.com comp.lang.ada:42051 Date: 2003-09-01T20:59:20-05:00 List-Id: Marin David Condic wrote: > Documentation can only be as good as the writer. Let's put this in And the writers of most (not all) online help files should have been politications--they don't let their lack of anything to say stop them from generating plenty of words. > got a single sentence saying "This is the gazorenthorpe subroutine", you > got something close to useless. If it gave you a page that described If the thing I pointed to was the identifier "gazorenthorpe," it would be _completely_ useless--yet typical of much of the help files from Microsoft, Apple, Dell, Gateway, Rational, Sun, and numerous other vendors. > 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. Indeed it would be. I'll have to take your word for it if you say that M$ broke character and did that sort of thing for MSVC++ > 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. -- Wes Groleau ---- The man who reads nothing at all is better educated than the man who reads nothing but newspapers. -- Thomas Jefferson The man who reads nothing at all is at least as educated as the man who reads nothing but online help. -- Wes Groleau :-)