Re: Software Engineers and Documentation

From: [at]} <Stan>
Date: Thu, 4 Mar 99 13:56:54 PST

Douglas Danforth wrote:

> Human, however, do not think this way. To learn
> and know something we need multiple cross references
> to the thing. High redundancy aids in memory and
> efficient retrieval given partial information.

...

> Documentation of computer systems should represent
> concepts from multiple views: syntax, preconditions,
> motivation for use, examples, more examples with
> variations, simplistic descriptions, detailed descriptions,
> goals of creators, weights (this is easy, this is hard),
> analogies (this is like a ...), why this is needed,
> and more.

But this is the difference between documentation and
a book. Documentation should be concise because it is
a specification. BlackBox documentation is excellent
for its intended purpose--a reference. I wrote the
"BlackBox Tutorial" because my students need a book
from which to learn. This distinction between documentation

for reference and a book for learning is why I stated
in an earlier post that we need a new book on component
programming with BlackBox. We should not expect the
documentation to fill that role.

Stan
=============================
J. Stanley Warford
Professor of Computer Science
Pepperdine University
Malibu, CA 90263
warford{([at]})nowhere.xy
=============================
Received on Thu Mar 04 1999 - 23:00:59 UTC

This archive was generated by hypermail 2.3.0 : Thu Sep 26 2013 - 06:27:42 UTC