Friday, January 9th, 2009
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 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.
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