Thank you Venkat for reminding me of a follow up
I wanted to express concerning documentation.
Here it is:
For concise, efficient, programs the principle
of "one place only" can and should be applied.
That is, use named constants rather than numeric
values in code. This also applies to object
oriented systems where "reuse" of objects and
components are encouraged.
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.
Cross reference using multiple words for the
same concept helps to disambiguate the "meaning"
of the concept. For example "string" is ambiguous
unless used in many contexts.
This human need is at variance with computer
efficiency. Hence concise documentation following
the computer principle is not the best way to
represent knowledge.
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.
The problem with writing such documents is that
maintaining them when systems change is a nightmare.
Where are all the references to this concept that
I just changed. I think a hyperlinked document
with "backpointers" (doubly linked lists) could
easy the pain of such maintainance.
And, yes, I think OuS has done a good job at what
they set out to do. I just wish the issue of
"component" design were surpressed (discussed
less) and "how do I use this system" emphasized
more.
-Doug
On Thu, 4 Mar 1999, Venkat Rao wrote:
> Blackbox Users:
>
> I agree that documentation is an often short shrifted. But its
> importance cannot be over-emphasized and I agree that it can contribute
> significantly to improved design and coding. Something that is hard to
> document is probably hard to use and hard to construct reliably.
>
> But I must defend OuS on the overall quality of their documentation.
> Even errors are relatively easy to spot, because of the clarity of
> preceding and subsequent paragraphs. The quantity of documentation to
> master is significant, but that appears to be inherent in the nature of
> frameworks of this sort. Compared to Java, it is indeed compact.
>
> Venkat Rao
> GTE
>
Douglas G. Danforth, Ph.D., danforth{([at]})nowhere.xy
Visiting Scholar Applied Speech Technology Lab (415)723-2487 pho
Center for the Study of Language and Information (415)725-2166 fax
Ventura Hall, Stanford University, Stanford CA. 94305-4115
Received on Thu Mar 04 1999 - 19:14:43 UTC