Friday, January 9th, 2009

Beautiful Code Documentation

Category: jQuery, Library

Atul Varma (who I have the absolute pleasure to work with now) has created code documentation that actually looks beautiful. Typography matters.

You can check it out via his Ubiquity documentation example that shows you side by side documentation with the actual source code itself. This context is terrific. He does this all dynamically, and uses border padding to align the documentation with the code itself.

Here is what he has to say about how it is done:

The raw source code for the file being documented above just has chunks of comments that are marked-up in WikiCreole; when the parser runs into such a chunk, it renders it alongside the code it annotates using Ivan Fomichev and Chris Purcell’s JavaScript Creole 1.0 Parser.

The idea of using the documentation to annotate the code—or the code to annotate the documentation, depending on how you look at it—was inspired in part by some of the typography presented in Ellen Lupton’s excellent Thinking with Type, which I recommend to anyone interested in the field.

It’s nice not having a separate documentation build step: aside from making the process of writing and editing documentation quicker, it also lowers the barrier for entry to contributors since they don’t need to setup a toolchain. It also means that we get versioned documentation in every commit for free.

Right now there isn’t much else to the system; the only other feature I added is the auto-generation of quasimodal popup menus that link the names of XPCOM interfaces to their entries on XUL Planet and MDC. It’d be nice to have more features like this; other niceties would be an automatically-generated table of contents, JavaScript Doctests, search functionality, cross references to other code, and even the ability to fix code formatting errors in-page. For now, though, I need to focus on actually using this tool to document more code.

As soon as Ben and I saw this our minds started to race. What if you could navigate the code via hyperlinks too? Or have groups comment inline? Many exciting ideas.

It is fun to see the 80 character column limit in place (and seeing where that is ignored). 80 character limits with wide screen displays? I never get that :)

Posted by Dion Almaer at 9:11 am

3.5 rating from 59 votes


Comments feed TrackBack URI

Very cool stuff – too much documentation out there is near unreadable

Comment by Artforge — January 9, 2009

The 80 column limit is actually probably too large.

It is well known that whatever is in front of a line is more readable. Long lines are difficult to read.

If you enjoy nice type fonts then you should also enjoy good style.

BTW: I am style looking for a text editor that would make wide screen useful using multi-column editing, like news papers do.

Comment by JeanHuguesRobert — January 9, 2009

This reminds me of “Literate Programming” that Knuth had written about many years back. If you ever used TeX or LaTeX for formatting papers/theses, the source code for the typesetting engine could be formatted as a book and was meant to be read as one.

Comment by Rino — January 9, 2009

syntax highlighting wouldn’t hurt on the code,

Very cool idea though, I applaud your efforts!

Comment by jaimz — January 10, 2009


I hope that’s intended for printing, not actually using on the screen as actual, useful documentation?

Because it’s completely useless for that.

Documentation that’s useable on screen?

Comment by ExtAnimal — January 10, 2009

Very sexy the extjs documentation .. is there a generator for that?

Comment by Aimos — January 10, 2009

Uhm, renders bad under Safari 3.0

Comment by DelfiRamirez — January 10, 2009

“BTW: I am style looking for a text editor that would make wide screen useful using multi-column editing, like news papers do.”
Oh my god, if I knew even a little bit of Cocoa I’d be trying to build a TextMate plugin to do exactly that. What a fantastic idea.

Comment by eyelidlessness — January 10, 2009

Leave a comment

You must be logged in to post a comment.