[plt-scheme] Vision behind Scribble

On Tue, 2008-03-18 at 12:18 -0400, hendrik at topoi.pooq.com wrote:
   . . .
> I've found that generating documentation in the source code normally 
> solves half the problem.  It does document the API in the sense that you 
> know what functions are available to be called.  But someone writing a 
> documentation comment does it in the context of the source code,  
> whereas it is usually read outside that context.  Furthermore, said 
> documentation rarely explains the conceptual structure of the 
> application, which makes the function-by-function documentation comments 
> incomprehensible.  Finally, there's no clue provided as to in which 
> combinations the functions are intended to be used.
   . . .
> The best example I've seen of a well-done manual set was the manuals for 
> OS/360.  Each major systems component was described in two manuals -- 
> the reference manual, and the Concepts and Facilities manual.  You read 
> Concepts and Facilities to determine what the subsystem did, whether it 
> met your needs, and hence how to organise your algorithms and programs.  
> You read the reference manual to determine where to put the commas and 
> operands while you were coding.

I had similar thoughts when I read this thread.  I learned a system
based on the distinction between internal documentation and external
documentation.  The internal documentation was the
per-function/module/class/... commentary.  This specified signatures,
gosintas/gosoutas and functionality of functions, etc. in detail.  The
external documentation contained architecture, so-called "Theory of
Operation", and described what the system did.  I liken the difference,
and the mandate to provide both, to practice in electronics engineering,
where block diagrams and theory of operation are provided in addition to
an annotated schematic.  The schematic is priceless when I'm
trouble-shooting, but when I'm trying to use the device it's nearly
useless but the other stuff is what's needed.

 -- Bill Wood