[plt-dev] documentation enhancements

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Thu Feb 19 16:49:00 EST 2009

At Thu, 19 Feb 2009 14:46:03 -0700, Jon Rafkind wrote:
> Two things would make the documentation much better
> 1. Always give the collection/library that a definition is part of. Some 
> parts of the documentation say (require ...) at the top but not all do. 
> In the end I resort to grep -r to figure out which collection to 
> include. Adding the collection name seems like it could be done 
> automatically.

Let the mouse hover over a defined name, and a pop up tell you where it
comes from.

I tried a couple of times to squeeze the name of the exporting library
into the definition box, but it looked too noisy to me. Specific
suggestions are welcome.

> 2. More examples would help (and yes I said I would write them before 
> but now I'm really going to do it) but I can see how some people would 
> find them annoying. Hiding them at first behind a div tag and a link 
> that unhides them might be a good option. I think this is reasonable 
> since the documentation already heavily uses javascript.

I think there's little danger of examples being annoying.

Posted on the dev mailing list.