What's the most loathed activity in the software development? It just might be writing documentation. I know I've dreaded it my entire career, and who wouldn't? Almost always, it's boring prose about boring code that no one is ever going to read.
Documentation doesn't have to be evil, though. Recently at Famigo, I had to write a metric butt load of documentation about our API for family gaming. I was so tempted to grumble my way through it, vomiting words into vi as quickly as possible so I could get back into the code. I didn't, though. Instead, I made into a project as challenging as any code that I've written in a while, and I think the results speak for themselves.
How do you challenge yourself to make great, engaging documentation? I found 2 different ways.
The first way was simple: I would accept nothing less from myself than funny, smart, interesting writing. Can you do that when you're writing about APIs? Hell yeah you can! I did it through copious footnotes chockfull of jokes about Short Circuit and Arrested Development. Between all of the jokes, there's a hell of a lot of content. I did example after example, trying to create a cohesive point of view throughout the doc. Yeah, the documentation's funny, but it's also engaging and informative.
Have you ever read a wonderful essay? A perfect example here is Tennis, Trigonometry, Tornadoes by David Foster Wallace. If you read that, then yeah, it's non-fiction and you learn a little bit. But you get more out of it than just the knowledge there. You're entertained, you're informed, it makes you think a little bit; it's like talking to a mad genius. Now, none of us can write documentation like David Foster Wallace. (At my best, I'm like his half-retarded cousin.) But we can use that sort of writing as a goal, and try our best to match it. It took me days, but I am proud of the results! You can see for yourself.
The second way to challenge myself was a little more complicated. I wanted an HTML listing of all of the methods in the API, along with basic info like the expected parameters for each call and each method's doc string. There are tools that can analyze your codebase and spit that out in a few seconds; Epydoc is one good example for Python. There's not much of a challenge to running Epydoc, though. I decided to write my own badass Python parser to generate documentation.
Why write that myself? First, it's fun. Second, I used a lot of coding conventions throughout the API. I figured that if I had a way to parse the code for those conventions and generate documentation from those, it'd be an even better level of detail. Third, I wanted to be able to include and exclude chunks of the documentation programmatically, rather than having to fire up a text editor and mangle the automated output from Epydoc.
It ultimately took me about 8 hours to get famidoc (clever naming ftw!) powerful enough to analyze our code and generate great documentation. Sure, I could've spent that time doing something else. However, I'll need to regenerate this method listing whenever the API changes; it's nice to automate that. Not only that, but famidoc showed me the few instances where methods weren't properly documented or deviated from my coding standards. My documentation resulted in better software! Here's the final result from famidoc.
With both of these challenges in place, it took me much longer to create this documentation. Was it a waste of time? I don't think so. This documentation is so much better than what I've created before; anyone who wants to interface with Famigo now has a wealth of information to work with, and they might actually enjoy reading it. Also, it was so beneficial to think about the code from this different perspective. I made a ton of tweaks, based on minor inconsistencies I had never seen before. Finally, it was fun. If I'm having fun, I'm doing better work.
Am I taking this same approach the next time I have to write some documentation? You bet your sweet bippy I am.