[plt-scheme] Vision behind Scribble

On Mon, Mar 17, 2008 at 04:29:58PM +0000, Noel Welsh wrote:
> On Mon, Mar 17, 2008 at 4:21 PM, Grant Rettke <grettke at acm.org> wrote:
> > I had a look at the Scribble docs. I'm not sure how to communicate
> >  this, but, they have a "light" feeling. They are nice to read.
> >
> >  What was the vision that drove Scribble?
> >
> >  For example, why did you choose to keep your documentation for the
> >  source code separate from the source code?
> 
> I don't know why Matthew made that decision, but having written
> Javadoc documentation, and attempted to do the same in Scheme, I have
> found it doesn't work well.  Javadoc docs don't flow well.  They are
> fine for API references but not for anything else.  Macros mean that
> what you want to document may not even be apparent in the source file,
> so where do you place the documentation?  Finally, the documentation
> gets in the way of the code, and vice versa.
> 
> N.

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.

And when such systems get used in practise, one usually gets pages and 
pages of static type information about API entry-points, with nothing 
but the function name to explain what they do.  Make no mistake, that is 
sometimes sufficient, but usually it is not.  The programmers have not 
looked at the code from the documentation reader's viewpoint.

One example where the documentation-from-source-code was done well was 
the Trestle manual, part of the Modula-3 system.  But that was done by 
masters of the art who were fully cognisant of the need to produce a 
real manual, and even it is somewhat lacking. 

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.

Machine-generated documentation tends to tell you where to put the 
commas and operands, not what any of it means.

It takes someone with a gift for technical writing to do better.  
Perhaps the essential part of the gift consists merely of a 
determination to do better, to pay attention to the documentation that 
is produced, and to treat the documentation as being as much a 
debuggable output from the program as its execution is.

-- hendrik