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 <jgoerzen@complete.org>
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.