Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!watmath!clyde!burl!ulysses!allegra!mit-eddie!genrad!panda!talcott!harvard!seismo!brl-adm!brl-smoke!smoke!MRC%PANDA@sumex-aim.arpa
From: MRC%PANDA@sumex-aim.arpa (Mark Crispin)
Newsgroups: net.unix-wizards
Subject: Re:  job control
Message-ID: <35@brl-smoke.ARPA>
Date: Tue, 15-Apr-86 21:23:07 EST
Article-I.D.: brl-smok.35
Posted: Tue Apr 15 21:23:07 1986
Date-Received: Fri, 18-Apr-86 04:41:05 EST
Sender: news@brl-smoke.ARPA
Lines: 34

Barry -

     The online documentation needs a good KWIC index, and the
hardcopy documentation needs a real index, e.g.:
	TERMINAL
	 hung terminals, fixing			844
	 interconnection			223
	 reading parameters			111, 143(fn), 432
	 setting parameters			113-116, 124, 322
	 using terminals as a device		53-55

     Basically, *every time* some technique is described, it
should get an index marker.  I have no idea if troff or nroff or
whatever is in vogue can do this; if not dump it and use a real
document formatter such as Scribe.

     Look in any well-organized reference manual index or even
better, look at any history book with indices and footnotes.
Such things can be done; it just takes a person with more than a
6th grade education in writing skills and the English language.
Yes, many hackers are functionally illiterate, but I know that
isn't the universal case.

      There really isn't much of a comparision between the
TOPS-20 documentation and Unix.  There's too much TOPS-20
documentation (it needs 5 strong men to carry all of it), and
very little of it is available online.  Most TOPS-20 programs are
intrinsically self-documenting, which helps.  And, equally
important, most TOPS-20 manuals have a REAL index!  Since the
Unix documentation is so small, it should be possible to index
the entire documentation set.

-- Mark --
-------