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=1.9 required=5.0 tests=BAYES_50,INVALID_DATE, MSGID_SHORT autolearn=no autolearn_force=no version=3.4.4 Path: utzoo!yunexus!geac!geaclib!daveb From: daveb@geaclib.UUCP (David Collier-Brown) Newsgroups: comp.lang.ada Subject: Re: documentation of software Message-ID: <3739@geaclib.UUCP> Date: 5 Mar 89 22:08:47 GMT Article-I.D.: geaclib.3739 References: <7005@zodiac.UUCP> Organization: GEAC Computers, Toronto, CANADA List-Id: >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