rockmore@zodiac.ADS.COM (A. Joseph Rockmore) (02/28/89)
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
...joedaveb@geaclib.UUCP (David Collier-Brown) (03/06/89)
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