Text File

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.