From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=0.6 required=5.0 tests=BAYES_05,INVALID_DATE
	autolearn=no autolearn_force=no version=3.4.4
Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!ucbvax!TAMUNIX.BITNET!cyclops
From: cyclops@TAMUNIX.BITNET (Glenn Vanderburg)
Newsgroups: comp.lang.ada
Subject: an interesting perspective on documentation
Message-ID: <8902271704.AA12256@ajpo.sei.cmu.edu>
Date: 27 Feb 89 16:08:18 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Organization: The Internet
List-Id: <comp.lang.ada>

All this talk about code documentation has reminded me of a rather
interesting idea I ran across a while back in some documentation
for Donald Knuth's WEB system.

   (For those of you who aren't familiar with it, WEB is a system for
   integrating Pascal code with TeX documentation.  It also offers some
   extra support for modular coding which is precluded by ordinary Pascal
   syntax.  See Jon Bentley's "Programming Pearls" column, CACM, May and
   June 1986, for a good introduction.  WEB is certainly not without
   problems, but it is a fascinating concept, and it's hard not to be
   impressed when you can pick up a listing of a program as large and
   complex as TeX, start reading it from the beginning like a novel, and
   understand it easily).

The thing about WEB that has had the biggest impact on me is something
that Knuth just hints at, and never explicitly states (so far as I
know).  The title of the WEB manual is "The WEB system of structured
documentation," and while that's the only mention of the phrase
"structured documentation," I think that it's the pivotal phrase of
the entire document.  It really makes a difference to see the central
task of programming as documentation.  Now, the main audience is
readers, not the machine.  And, with a little discipline, you can
structure the documentation so that the machine can understand and act
on the same document.  And you don't even have to use WEB to do it!

Thoughts?  Not a panacea, certainly, but it's a very intriguing idea.

Glenn Vanderburg
cyclops@tamunix.bitnet