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