Re: Software Engineers and Documentation

Stan Warford (warford@pepperdine.edu)
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@pepperdine.edu
=============================