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.8 required=5.0 tests=BAYES_00,INVALID_DATE,
	MSGID_SHORT autolearn=no autolearn_force=no version=3.4.4
Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!ames!zodiac!rockmore
From: rockmore@zodiac.ADS.COM (A. Joseph Rockmore)
Newsgroups: comp.lang.ada
Subject: documentation of software
Message-ID: <7005@zodiac.UUCP>
Date: 28 Feb 89 15:04:55 GMT
References: <8902271704.AA12256@ajpo.sei.cmu.edu>
Sender: news@zodiac.UUCP
In-reply-to: cyclops@TAMUNIX.BITNET's message of 27 Feb 89 16:08:18 GMT
List-Id: <comp.lang.ada>


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