Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!think.com!zaphod.mps.ohio-state.edu!mips!pacbell.com!tandem!netcomsv!jls
From: jls@netcom.COM (Jim Showalter)
Newsgroups: comp.software-eng
Subject: Re: Accepted Practices
Message-ID: <1991Jun7.202628.12424@netcom.COM>
Date: 7 Jun 91 20:26:28 GMT
References: <1991Jun6.125833.18549@dec254.uucp> <1991Jun6.101639.1@happy.colorado.edu> <1991Jun7.171606.5862@intellistor.com>
Distribution: usa
Organization: Netcom - Online Communication Services  UNIX System {408 241-9760 guest}
Lines: 38

>Unfortunately, from what I can tell the emphasis in documentation
>standards (whether IEEE or DOD 2167) seems to be in generating paper
>in the correct format.  Very often format is more important than
>content when documents are required.  While supposed to improve
>software quality, they seem to do so by making it as hard as possible
>to make a change to allegedly working software.

You'll get no argument from me: almost all of the documentation
standards I've encountered are the triumph of form over function, of
style over substance, of sizzle over steak (the European HOOD standard
is a notable exception). I've seen projects mired in documentation
overhead to the extent that the tail wagged the dog--legitimate design
improvements were weighed against their impact on the documentation,
and the documentation group wound up wielding more political might than
the developers! I think the emphasis on form over content is pretty
easy to explain--form can be checked by people with no understanding
at all of software, design, or much of anything else (after all, how
hard can it be to verify that all 6-level nested paragraphs are in
12 point font?), whereas actually evaluating the CONTENT requires skill
and expertise.

Fortunately, for projects that have such standards inflicted on them,
there is a ray of hope: much of this sort of documentation can be
programmatically generated. Some might argue that this defeats the
whole purpose of documentation--which, allegedly, is to produce USEFUL
documentation--but so little of the documentation I've seen is actually
useful that it might as well be generated automatically. Note that this
ability to regenerate all of the documentation at will is a boon to those
projects wishing to use a more iterative (as opposed to waterfall) style
of development, since it removes the cost associated with constantly
reworking the documents. I can point you to a system that generates
documents automatically from Ada PDL and bubble-and-arc diagrams if
you're interested.
-- 
**************** JIM SHOWALTER, jls@netcom.com, (408) 243-0630 ****************
*Proven solutions to software problems. Consulting and training on all aspects*
*of software development. Management/process/methodology. Architecture/design/*
*reuse. Quality/productivity. Risk reduction. EFFECTIVE OO usage. Ada/C++.    *