[plt-scheme] Vision behind Scribble

On Tue, Mar 18, 2008 at 12:54:11PM -0400, Doug Orleans wrote:
> For me, the biggest reason to put the documentation in the source code
> is to reduce the chance of them getting out of sync.  It's much easier
> to update the documentation when it's right there next to the code
> than if it's in some other file.  But maybe this could be done better
> with the right tools-- maybe a hyperlink next to the code that brings
> you to the appropriate doc file to edit.  Are there any systems
> (e.g. Emacs packages) that work like this?

Yes, documentation should be in the source code.  It's the only way to 
keep it in sync, and that only if the programmers go to the trouble of 
maintaining it.  It it's separated from the source code, it will get 
lost.

But not all the documentation fits with the source code.  Perhaps the 
most prominent example is a system which consists of multipls source 
files.  The documentation that explains the large-scale structure or
the purpose of the system or how the end-user should approach it does 
not belong in any of the pieces.

No.  This isn't a solution.  The solutions we have solve only parts 
of the problem.  That doesn't mean they're useless.  It means that we 
have to recognise their limitations and do the extra ourselves.

-- hendrik