[plt-scheme] Vision behind Scribble

From: Noel Welsh (noelwelsh at gmail.com)
Date: Mon Mar 17 12:29:58 EDT 2008

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.


Posted on the users mailing list.