Aihuxg.112
fa.unix-wizards
utzoo!decvax!ucbvax!mhtsa!ihnss!ihuxg!grg
Mon Aug 24 15:07:18 1981
UNIX; Documentation??
In response to some recent UNIX documentation and interface discussions,
I think that the two are blurred.  The interface is criticized because
ti is poorly documented.  Invalid!!

I would agree with suggestions to improve the documentation;
UNIX documentation here exists in two levels only; casual (man), and
source, and the source is code only (VERY few comments).

 I think documentation should exist at several levels:

         0) intro: tutorial, documents.
               should be accesable by name, or by function.
         1) man:  reference, quick guide.
               current version is OK, should give more examples.
         2) online:  immediate.
               man is OK, breifer version would be good.
               Keywords and appropros best.
         3) system:  expert user, modifier.
               Clear documentation of external interfaces,
               assumptions, problems.
         4) internal:  hacker, maintainer.
               C code is often a reflection of the "NFS" tradition.

The code written for UNIX is perhaps the least documented I have
seen on any system.  Perhaps this is egoless programmming, i.e. no-one
will claim it.  The flavor I get is the "hard-core only", macho UNIX
"if you have to ask, you shouldn't be reading this.." stuff.
What ever happened to clarity as a criteria of expression?

Ever wonder how the uucp protocol works? (e.g. want to interface
to it..) Documented?  NO WAY!!  It always seems that there must be
somewhere a file with all the goodies accumulated by someone who
created/maintained a program for any period of time, but if so it's
lost on level 18 under a secret trap door...

I thought the Lyons UNIX course books were excellent.  Why they haven't
ever been updated, especially with the money we at BTL spend growing
UNIX experts is beyond me.

I would think that documentation at the various levels would make
code maintenance easier, and be cost effective.

-----------------------------------------------------------------
gopher://quux.org/ conversion by John Goerzen <[email protected]>
of http://communication.ucsd.edu/A-News/


This Usenet Oldnews Archive
article may be copied and distributed freely, provided:

1. There is no money collected for the text(s) of the articles.

2. The following notice remains appended to each copy:

The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996
Bruce Jones, Henry Spencer, David Wiseman.