baur@spp2.UUCP (Steven L. Baur) (03/16/89)
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.
friedl@vsi.COM (Stephen J. Friedl) (03/20/89)
In article <1689@spp2.UUCP>, baur@spp2.UUCP (Steven L. Baur) writes: > Has anyone else noticed how far AT&T documentation has fallen? This has not been our experience: three books is not a good sample. We've been pretty immersed in the 3B2/3B15/3B4000 product line for almost five years, and we've seen the quality of documentation improving dramatically. While the older docs may not be thoroughly revised, the new documentation is really very good. Their new device driver books are fantastic, as is just about everything for the 3B15 Sys V Rel 3. In addition, the SVID is good and getting better. AT&T has a lot of good tech writers, and they are using them. Steve -- Stephen J. Friedl / V-Systems, Inc. / Santa Ana, CA / +1 714 545 6442 3B2-kind-of-guy / friedl@vsi.com / {attmail, uunet, etc}!vsi!friedl "I think, therefore I'm a yam." - me