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.