Re: 2167A

Re: 2167A

[Ken Garlington]

Fred McCall <merlin@ANNWFN.COM> writes:

<< Not to mention its [DoD-STD-2167A's] insistence on reams of meaningless
verbosity in the way of documentation. >>

Unless, of course, you tailor that documentation to fit your needs. Of course,
everyone knows that if you do NO documentation, you get really low development
costs. (Life cycle costs are a different question, but that always seems to be
somebody else's problem. ;)

It's going to be interesting to see what happens if DoD dumps Dod-STD-2167A
(and DoD-STD-SDD), but insists on an SEI III process (and to a lesser extent
one that incorporates the ISO 9000 series guidebook on software quality).
Humphrey's book implies that there's still plenty of documentation required for
a good project. Of course, he makes explicit things that 2167A assumes you
already know, like the importance of automating documentation as a by-product
of the process, etc.

It's also going to be interesting to see if the Government decides to adopt
another "best commercial practice" - the company that builds the software also
gets to maintain it. If Microsoft had to turn over maintenance of their
products to DoD, what would they cost and what would Microsoft's documentation
look like?

I've seen "best commericial practice" in action. A very large commercial
computer company recently released a product to us that was completely
unusable. After meeting with this company, they've decided to actually hire
someone to test this product before it ships, and to write down the test cases
before they are performed. I certainly can see where "best commercial practice"
is cheap, all right.

BTW, Ada is a commercial standard (and public law), so there isn't a corollary
to the use of DoD-STD-xxxx.

Re: 2167A

[Rod Cheshire]

Dammm!!!!! someone thought of it first

Re: 2167A

[Robert Dewar]

The biggest weakness of documentation in my experience occurs when it is
prepared independently from the source code. It is almost inevitable that
in this case the documentation does NOT get properly maintained, and quickly
becomes useless.

That's why I *much* prefer the practice of putting extensive high level
documentation in the source files, and then insisting that they be updated
as the sources are updated.

This is very hard to achieve. 

Many projects which appear to have wonderful documentation, as measured
by quantity and surface appearence of the documentation, in fact are in
terrible shape. This is especially true when the existence of the external
documentation persuades people that it is unnecssary to document the
code.

Re: 2167A

[Ken Garlington]

Lee_Robert_Willis@CUP.PORTAL.COM writes:

<< Usually the tailoring must be done way in advance.... It has been my
unfortunate experience that the people involved before phase X don't know or
give a damn about the 2167A docs for phase X, and thus very little tailoring
happens. >>

Sounds like a lousy customer. We're on rev. "C" of our F-22 SDP, and we've done
lots of Just In Time tailoring. It also helps if you've got some experience
with mil-spec contracts, so you know in advance what's worthless ;)

Trying to maintain some semblance of Ada relevance, we've got an optional
tailoring of Section 4 (Detailed Design) of the SDD that's built from the Ada
code. We use the Cadre a_reveng tool to build Ada Structure Graphs from
suitable collections of Ada units, and then use a feature called Active Links
in our Interleaf documents to extract Ada source code (with appropriate
comments describing requirements traceability, etc.) from the CM system, format
it, and put it in the document at the right paragraph with all the security
markings automatically generated from the comments. Once you have the structure
of the document set up, the document updates itself. We can also build
identifier indexes, requirements traceability tables, etc. right from the code.
Very low-cost approach to produce good-looking (and current!) documentation.