Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!ames!lll-winken!uunet!wiley!spp2!baur
From: baur@spp2.UUCP (Steven L. Baur)
Newsgroups: comp.sys.att
Subject: The Declining Quality of AT&T Documentation
Message-ID: <1689@spp2.UUCP>
Date: 16 Mar 89 09:07:13 GMT
Reply-To: baur@spp2.UUCP (Steven L. Baur)
Organization: TRW Inc., Redondo Beach, CA
Lines: 52

Has anyone else noticed how far AT&T documentation has fallen?
I have before me three books.  The first is UNIX programmer's manual
REVISED AND EXPANDED VERSION (ISBN 0-03-061743-x (v.2)).  (The green
book from 1983).  This has everything I would expect from an excellent
manual.  It has lots of examples and a detailed index.  Both the first
volume (the blue book) and this one I have used as examples as ideal
examples of how a manual ought to be written:
The functions are broken up into distinct sections (command, system
call, library call, ...), and the index is excellent.

Now lets look at some more recent publications.  How about
"The UNIX System User's Manual (ISBN 0-13-938242-9)"?
This manual is pre-SVID (barely), and comes with the following features:
* no index.
* no ordering in alphabetical order of routine by function.
* no table of contents.

This is thoroughly frustrating to find information out of.

How about "The UNIX programmer's manual" from CBS COLLEGE PUBLISHINGS?
The volume I have in front of me is the Document Preparation (Vol 4)
book.  It has no index, a very detailed table of contents, and a
disorganized style.  All in all, it is a perfect example of a terrible
manual.

Now, I am attempting to write a document using the MM macros.  I have
an AT&T UNIX PC, but no documentation on Documentation Workbench other
than how to invoke it.  So I turn to the UNIX programmmer's manual vol.
4 for document preparation (it has documentation on how the MM macros
work).  A tad hard to follow, but that doesn't really matter.
Now I want to create a table in my document and ...
there are no examples in that book (sigh).

Turning back to my ancient UNIX Version 7 documentation (the Green book)
I find the first part of the chapter on tbl, but there are numerous
examples following.

So, I recommend that you do not throw away your old UNIX documentation
but save it.  As AT&T documentation quality deteriorates you will be
glad you did.

steve	uunet!wiley!spp2!baur

PS:  On the UNIXPC/DWB for UNIX 3.51 the subj(1) program (a shell script
actually), has a stupid bug in it that prevents it from running entirely.
In the first for loop remove the \( -r $arg \) and replace $i (for $arg).

For an operating system originally sold as a replacement for a documentation
system UNIX has come a long ways.

.PSS:  To be fair, no *tex document I have ever gotten has ever formatted
correctly on the first try.