an interesting perspective on documentation

an interesting perspective on documentation

[Glenn Vanderburg]

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

documentation of software

[A. Joseph Rockmore]

glenn vanderburg points out that don knuth's WEB system, as a system
for "structured documentation", emphasizes that the central task of
programming is documentation.  the current DoD standard for software
development, DOD-STD-2167A, has the same viewpoint (although not as
integrated as knuth's, of course).  when people first read -2167,
their reaction is often "gee, all this emphasis on documentation...
when does the damn thing talk about *coding*?"  but in the world of
real, large, complex software systems, getting all the documentation
right (consistent, complete, etc.) is a far greater part of building a
software system than is the coding.

on the topic of documentation, what are the feelings out there in
internet-land about the *minimum* documentation requirements that make
sense.  let me put forth a (ahem) modest proposal: the miminum
documents that any software development effort should produce are a
requirements document, a design document, the code listings, a test
report (including the test cases, procedures, and results), a user's
manual, and an operator's manual.  notice that these are all
"products" of the software development effort-that is, they, taken
together, will describe what the code does.  in addition, there are
documents that deal with the "process" of developing the products, and
my proposed minimum set is a software development plan and a software
test plan.  are these sufficient?  can any be left out?  under what
circumstances can/should some be added or deleted?  opinions
appreciated.

	...joe

----------
   Path: zodiac!ames!pasteur!ucbvax!TAMUNIX.BITNET!cyclops
   From: cyclops@TAMUNIX.BITNET (Glenn Vanderburg)
   Newsgroups: comp.lang.ada
   Date: 27 Feb 89 16:08:18 GMT
   Sender: daemon@ucbvax.BERKELEY.EDU
   Organization: The Internet
   Lines: 29

   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


	...joe

Re: an interesting perspective on documentation

[Scott Simpson]

In article <8902271704.AA12256@ajpo.sei.cmu.edu> cyclops@TAMUNIX.BITNET (Glenn Vanderburg) writes:
>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.

I like WEB and I think mixing program and documentation is a good
idea.  I wish there was an Ada version so I could experiment with it.
I don't ever use Pascal any more.  I imagine an Ada version would have
slightly different WEB control sequences though since the semantics of
the two languages differ.
	I have some problems with it though.  First, WEB utilities
(i.e., tangle, weave) act as preprocessors.  I usually don't
like preprocessors because you lose semantic information that debuggers
and other tools need.  This is one reason I thank God Ada does not use
a preprocessor and Stroustrup added constants to C++.  With WEB, you
can get errors at 3 levels: from WEB control sequences, from TeX
control sequences and from Pascal code.  Trying to find where the
errors are coming from can be somewhat confusing.
	I have another granularity problem with the way Knuth divided
up the code in TeX.  The code is divided up into so many small
chunks that it is hard to keep track of what goes where.  He has
devised an indexing scheme (i.e., the <...> notation) for keeping track
of all these divisions but I still think the level of "exploding" code
needs further investigation.  I like just putting comments at the
beginning of procedures/functions.  Other people differ.  I think the
name WEB for the TeX code is an accurate description though!

[[ Perhaps this discussion should move.  I leave it to someone else to
do this.]]
	Scott Simpson
	TRW Space and Defense Sector
	oberon!trwarcadia!simpson  		(UUCP)
	trwarcadia!simpson@oberon.usc.edu	(Internet)

Re: an interesting perspective on documentation

[David Guaspari]

Someone interested in a version of WEB for Ada might be
interested in a paper by Norman Ramsey,

    Building a language-independent WEB

which will be appearing in the CACM (I'm not sure when).  This
paper is also available as Tech Report 17-5 from

   Odyssey Research Associates
   301a Harris B. Dates Drive
   Ithaca, NY 14850-1313

Re: documentation of software

[David Collier-Brown]

From article <7005@zodiac.UUCP>, by rockmore@zodiac.ADS.COM (A. Joseph Rockmore):
> 
> glenn vanderburg points out that don knuth's WEB system, as a system
> for "structured documentation", emphasizes that the central task of
> programming is documentation.  the current DoD standard for software
> development, DOD-STD-2167A, has the same viewpoint (although not as
> integrated as knuth's, of course).

> let me put forth a (ahem) modest proposal: the miminum
> documents that any software development effort should produce are a
> requirements document, a design document, the code listings, a test
> report (including the test cases, procedures, and results), a user's
> manual, and an operator's manual. 

  Add to this the "program logic manual", which tells how the
program works and what to change to get it do something else.
This document is EXTREMELY hard to write, usually out of date and
often inaccurate.
  It is this which WEB contributes to, by making the program
comprehensable (in some senses)

  For certain classes of problem (reusable components, inherently
difficult algorithms, etc) this is very worthwhile.  Honeywell once
claimed you had to write one for everything, but eventually dropped
the requirement...
-- 
 David Collier-Brown.  | yunexus!lethe!dave
 Interleaf Canada Inc. |
 1550 Enterprise Rd.   | He's so smart he's dumb.
 Mississauga, Ontario  |       --Joyce C-B

Re: an interesting perspective on documentation

[horst]

The University of Oldenburg has done an implementation of WEB for Ada
in Ada. It is distributed freely if you wish. (Karl, do you want a
copy?)

Horst

Re: Re: an interesting perspective on documentation

[Eric A. Slutz]

Can you make the Ada-Web avalible to the net?

Re: Re: an interesting perspective on documentation

[horst]

In article 1122 of comp.lang.ada Eric A. Slutz asks for AWEB.

If no unexpected  difficulties  arise,  AWEB  should  be  on  the  Ada
Software  Repository  soon.  As  you  need a running TeX to output the
generated .tex files, maybe you have enough work until then :-).

Regards,
 Horst