Good documentation doesn’t come easy

Documenting source code is rarely something a coder likes to do. I’m just as guilty as anyone else. I know it’s a “good thing”, but my natural inclination is to code first and document later. Sometimes later comes so late that it’s a chore to get it done. I’ve been forcing myself to document as I go, and it usually works out pretty well in the end.

I’m a control freak

What’s made this process easier for me is to completely dump the notion of auto-generated documentation (I’m looking at you, javadoc, jsdoc, yuidoc, ruby-doc and the like). Instead, I favor writing the documentation for a given piece of code with markdown.

It’s a tradeoff between automation and control, and when it comes to documentation, I prefer the control.

I can start by documenting only that which is important. That satisfies the “write this down before I forget” part of documentation, and frees me up to improve it in later drafts. Yes, drafts (like a real piece of writing). I don’t have any “empty stubs” made for me, so at any given moment my documentation is fairly complete without extra noise.

Later, sometimes much later, I can add more to the documentation, including example code and other goodies. This way the documentation matures along with the code, which can be pretty cool.

This is not a new idea by any means. Most perl developers have used pod, which has a very similar approach but with a slightly less human-readable plaintext markup (I’m a CPAN contributor from way back, I’m allowed to dis pod a little). In fact, this style of code documentation goes way-way back. Before source code documentation compilers existed; back when you actually read the documentation as you read the code.

Along my source code documentation journey, I checked out “natural docs”, which looked very appealing. I was disappointed that while flexible, it went down the path of regimented source documentation. Also, I found that I preferred the simplicity of a plaintext formatting language like markdown, without having to worry about adding section types and such to the documentation compiler.

So, what then?

Enter jodoc

Last Spring, I wrote a simple set of perl scripts which takes embedded markdown docs (along with raw HTML pages and other markdown documents) and turns them into a pretty useful set of HTML documentation. This tool is called “jodoc”, and was written to support my HTML framework (Jo). I’ve been using this plaintext approach to source doc writing ever since, and I love it.

Basically, it takes something like this (found in my source code):

And spits out HTML which looks like this:

A couple examples

The first is the documentation for Jo itself, turned into one easily-searchable, cross-linked and PDFable single page of HTML: http://joapp.com/docs/.

The second is the documentation for PhoneGap, which is split into easily-grokkable and book-markable sections (with some nice CSS at work as well): http://docs.phonegap.com/.

The concept is simple

jodoc looks for markdown documentation in your code (it can be in one continuous block, or split into sequential pieces, your call). Then it assembles it into the structure you want, puts it into a single file, or adds a customizable table of contents (also defined with markdown) and splits your documentation into separate HTML files. For a final touch, it takes anything you’ve marked (using markdown, of course) as a main header (i.e. H1) and turns it into a fully-linked and indexed keyword. This means when you casually discuss a class or some term you’ve documented elsewhere, jodoc will make a link for you (think “wiki”, but without TheCaps).

It’s a simple idea, and folds nicely with doc files which live outside your code (either markdown or HTML, currently). We’re already working on some neat extensions, but since it’s open source, we’d love to see more contributions.

Give it a try

Dan Freedman, a friend and fellow HP engineer, took my crude perl script and banged it into shape. The result of which can be seen on GitHub, along with a new node.js version that’s already underway (go Dan!).

Perl: https://github.com/davebalmer/joDoc

Node.js: https://github.com/azakus/jodoc-js

If you’re dead-set on javadoc-style documentation, that’s fine. I’d invite you to give this sort of approach a try. Really: a serious try on your next hunk of code. You might find that you’re actually doing less work and getting better documentation for the effort.

About these ads