* documentation of software
1989-02-27 16:08 an interesting perspective on documentation Glenn Vanderburg
@ 1989-02-28 15:04 ` A. Joseph Rockmore
1989-03-05 22:08 ` David Collier-Brown
1989-03-01 18:27 ` an interesting perspective on documentation Scott Simpson
1989-03-20 17:15 ` Eric A. Slutz
2 siblings, 1 reply; 8+ messages in thread
From: A. Joseph Rockmore @ 1989-02-28 15:04 UTC (permalink / raw)
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
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: an interesting perspective on documentation
1989-02-27 16:08 an interesting perspective on documentation Glenn Vanderburg
1989-02-28 15:04 ` documentation of software A. Joseph Rockmore
@ 1989-03-01 18:27 ` Scott Simpson
1989-03-02 14:57 ` David Guaspari
1989-03-16 14:21 ` horst
1989-03-20 17:15 ` Eric A. Slutz
2 siblings, 2 replies; 8+ messages in thread
From: Scott Simpson @ 1989-03-01 18:27 UTC (permalink / raw)
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)
^ permalink raw reply [flat|nested] 8+ messages in thread