> From: Stan Warford <warford{([at]})nowhere.xy
> Subject: Re: Software Engineers and Documentation
> To: blackbox{([at]})nowhere.xy
> 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 would respectfully disagree. BlackBox documentation
is "pretty good" as a reference, but not excellent. There
are too many things that I've had to "figure out" on my
own or ask the mailing list because they weren't anywhere
to be found in the documentation. Things like "if you
want to retrieve the path from a locator you need to change
your Files.Locator to a HostFiles.Locator using a type
guard." Or "if you want to edit the comment section on
a StdStamp you need to hold down the Ctrl key and click
on it."
> 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> =============================
I agree that a book is needed and that the online documentation
will never fully fill the role of a book. But then I wouldn't
expect a book aimed at students learning the language to fully
fill the holes that currently exist in the "reference" part of the
current BlackBox documentation. I think a "user maintainted HOWTO"
reference site for BlackBox is needed.
Received on Thu Mar 04 1999 - 23:39:18 UTC