reg:exp

Where should I start? (API Documentation)

While preparing materials for a Processing workshop I will teach at the California College of Arts in a few weeks, a question I've been mulling over in recent weeks reared its head again:

If I am new to a particular API, how do I know where to start?

Automatically generated documentation such as Javadocs do a poor job at directing attention, because they do not convey any information about how a library is typically used. The Processing reference page is not much better - while it offers some thematic grouping, it still shows one big laundry list of functions that is hard to digest. Small examples and tutorials are great, but someone has to go through the trouble of writing them first.

Brad Myers, in his talk at NPUC 2009, mentioned two new research projects to improve API documentation at CMU: Apatite, and Jadeite. What immediately resonated with me in both projects was the use of variable font sizes to indicate relative importance or frequency of use of methods/classes/.... In other words, apply the tag cloud paradigm to API docs.

Can this approach help novices find their way through the Processing reference documentation? I wrote a small Python script to count occurences of function names in a corpus of ~1000 Processing source files, pulled from the Processing examples, files posted to the Processing forum, and ones retrieved by Google search for the .pde extension. The script then reformats the main reference page to show relative frequency of occurrence. Here are the results:

Appears promising, although there are still some wrinkles in the code to be ironed out (as always).