Try any of the Software Engineering books out there. They all
emphasize documentation to an anal degree. It's all interesting
theoretical reading, but nobody wants to pay for documentation.
It's only done by the better software engineers, and anyone who
has to work on a large project. In "Writing Better Computer User
Documentation" by R. John Brockman (ISBN 0-471-88472-3) a section
in the first chapter is titled "What Problems Does Inadequate
User Documentation Cause?" There's also a fairly extensive
bibliography. A really great book on software documentation (as
applied to building and maintaining systems) is "Structured
Analysis and System Specification" by Tom DeMarco (ISBN
0-13-854380-1). It does contain a section on the effect of SA on
the project life cycle. All these books argue how their
techniques will contribute to success; just reverse the arguments
to build a case for the cost of failure to document.
I'm of two minds on the subject of documentation. On the one hand
the code speaks for itself. It's always self-documenting in that
it says EXACTLY what the computer must do, and programmers who
use techniques like Hungarian notation and standardized styles
create even better self-documenting code. Source code is
precisely defined. When you read "INUM=7" in some source code,
there is no doubt that the value of INUM at that particular point
is precisely equal to seven. However, the reason for the
existence of INUM remains as ineffable as the meaning of life,
the universe, etc. And so that brings up the other side of the
question. Can you ever document enough?
Compare source code to a novel written in a language foreign to
you. At the lowest level, you need to know the definitions of the
words. At the next level, you need to know their meanings in the
context of each sentence. Any idioms or slang must be resolved at
this level too as well as the shades of time, subjects and
objects implied by the verbs and phrases. At higher levels you
have to document the interplay of characters, settings, plot and
so on. In the end a fully documented novel is bigger and more
work to read than the novel itself.
The real question is about a matter of degree. Failure to
document is bad, but so is over documenting, or mechanical
documenting. Notation techniques are important too. Personally I
like the Yourdan-DeMarco Structured Analysis method, because it
minimizes redundancy, and is therefore easier to maintain, but it
still has shortcomings when applied to highly interactive
software like what we have in the Windows environment.
I'd be interested in whatever you find too, because I am still
searching for the perfect method for documenting software from
design to maintenance and for programmer and user.
--
- Bill Thoen
------------------------------------------------------------
GISnet, 1401 Walnut St., Suite C, Boulder, CO 80302
tel: 303-786-9961, fax: 303-443-4856
mailto:[EMAIL PROTECTED], http://www.ctmap.com/gisnet
------------------------------------------------------------
[EMAIL PROTECTED] wrote:
>
> I'm doing some research on the impact of failure to document software
> systems and I'm wondering if any of you have any ideas on where to get this
> data.
>
> I've come across data on the impact of design failure but so far I have not
> come up with anything on documentation. What I'm looking for are figures
> that illustrate this impact.
>
> If anyone has any ideas on where I might find this, I'd like to hear from
> you.
_______________________________________________________________________
List hosting provided by Directions Magazine | www.directionsmag.com |
To unsubscribe, send e-mail to [EMAIL PROTECTED] and
put "unsubscribe MapInfo-L" in the message body.
