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.1 required=5.0 tests=BAYES_20,INVALID_DATE,
	MSGID_SHORT autolearn=no autolearn_force=no version=3.4.4
Path: utzoo!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!samsung!cg-atla!raybed2!rgc
From: rgc@raybed2.UUCP (RICK CARLE)
Newsgroups: comp.lang.ada
Subject: Re: Rational ADA development environment
Summary: Why so much documentation?  Answer: Dod-Std-2167
Message-ID: <1462@raybed2.UUCP>
Date: 12 Feb 90 14:43:50 GMT
References: <405@wmt.UUCP> <595@ns-mx.uiowa.edu> <4722@rtech.rtech.com>
Organization: Raytheon Co., Bedford, Mass.
List-Id: <comp.lang.ada>

In article <4722@rtech.rtech.com>, dennism@menace.rtech.COM (Dennis Moore) writes:
> Isn't this typical for a government project?!?  40,000 LOC and 2,500 pages
> of documentation? ...  > If ADA is such a wonderful, self-documenting, easy
> to code, easy to understand, > easy to maintain language (as the government
> claims it is), then why are 2,500 pages of documentation necessary?

DoD-Std-2167 (& 2167A) is the true culprit here.  Total ignorance of the
project in question does not inhibit me from suggesting that its
excessive documentation is caused by 4 related problems.
1) Dod-Std-2167 and its insistence on too many documents with too much
  detail, all to describe a single program (a 2167 CSCI).
2) The tendency of software designers to map Ada compilation units (ie,
  procedures, functions, tasks, packages) to 2167 "units" (2167A CSUs),
  thus producing excessive paragraphs in the 2167/A SDDD & SDD documents.
  It would be better to map Ada packages (or Library Unit Groups ala
  Kaye Grau/Kathy Gilroy) to 2167 units.
3) The tendency of software designers, using Ada PDL, to over-design
  practically to the point of coding.  This causes every line of code to
  be part of the design.  This tendency has always been a problem with
  software designers, but Ada PDL gives them the best tool ever for
  committing their sins.  One solution is simple restraint, perhaps
  enforced by management.  A more practical solution might simply be to
  design no deeper than package specs.
4) The failure of government contracting officers and industry proposal
  managers to routinely tailor 2167 to the needs of the particular
  contract.  Proponents of 2167 have claimed (don't expect me to provide
  sources of quotes) that tailoring is essential to the successful
  application of 2167, but few contracts follow that doctrine.

	Rick Carle