[CONTACT]

[ABOUT]

[POLICY]

[ADVERTISE]

Aihuxg.fa.wizardsutzoo!decvax!

Found at: gopher.quux.org:70/Archives/usenet-a-news/FA.unix-wizards/81.08.24_ihuxg.112_fa.unix-wizards.txt

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.

NEW PAGES:

[ODDNUGGET]

[GOPHER]