Xref: utzoo comp.lang.c:26652 comp.software-eng:3096
Path: utzoo!attcan!uunet!paralogics!shaw
From: shaw@paralogics.UUCP (Guy Shaw)
Newsgroups: comp.lang.c,comp.software-eng
Subject: Re: Currency Quotes
Summary: Howabout a CAVEATS section immediately followed by a BUGS section
Message-ID: <265@paralogics.UUCP>
Date: 7 Mar 90 09:11:55 GMT
References: <803@xyzzy.UUCP> <8229@hubcap.clemson.edu> <1990Mar4.235537.3757@oracle.com>
Organization: Paralogics; Santa Monica, CA
Lines: 53


Mr. Wolf's posting about "the C community's cavalier attitude toward software
reliability" encompassed enough subject matter that it was bound to generate
many threads about various aspects (sort of like sitcom spin-offs).  In this
article, I address only the issue of the appropriateness of lumping all manner
of shortcomings into the BUGS section of a reference manual.

In article <1990Mar4.235537.3757@oracle.com>, mfriedma@oracle.com (Michael Friedman) writes:
> In article <8229@hubcap.clemson.edu> billwolf%hazel.cs.clemson.edu@hubcap.clemson.edu writes:
> >   No, it was an example of the C community's cavalier attitude
> >   toward software reliability.  The comment "Don't base your
> >   financial plans on the output", or words to that effect, were
> >   a) inappropriate, since the static nature of the rates is part
> >   of the specification and should not be listed in the defects section
> >                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >   [...]
>
> I disagree.
>
> On point A you are technically correct - the possibly unreliable
> nature of the rates is part of the spec.  On the other hand, from the
> point of view of producing good results, that note is in exactly the
> right place.
[...]
> entry, but say we have something like csh.  I'm not going to read
> through a hundred pages looking for caveats and warnings.
          ^^^^^^^^^^^^^^^             ^^^^^^^^^^^^^^^^^^^^
>                                                            I want them
> in one simple clear easy to use location - the Bugs section. [...]

Yes, Mr. Wolf has a point and so does Mr. Friedman, but there are more
possibilities than just the two extremes of  a) lumping things in the BUGS
section and b) distributing caveats throughout the reference manual.
To be fair, Mr. Wolf did not offer (b) as the only alternative.  In fact,
he said nothing more specific about how he would organize a reference manual.
Mr. Friedman's reaction is very understandable, though, because caveats
sprinkled throughout the reference manual, where each subject naturally arises,
*is* the alternative style that actually occurs in AT&T UNIX reference manuals.
And, like diseases of the lymphatic system, it is nearly impossible to treat
with surgery.

The approach of having separate CAVEATS and BUGS sections solves the problem
of where to put limitations, shortcomings, non-intuitive behavior, etc. without
calling it all BUGS, and still lists them in one easy to find place.
It is more precise.  Nothing else is sacrificed for the the gain in precision.
This is more than just armchair reference manual designing.   I have used
slightly non-standard (improved!) UNIXoid manuals that do it this way.
It works for me.  I wish it were more common practice.  To the reference manual
designers at AT&T: try it, you'll like it.
-- 
Guy Shaw
Paralogics
paralogics!shaw@uunet.uu.net  or  uunet!paralogics!shaw