Re: documentation of software

[daveb@geaclib.UUCP (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