How Documentation Can Impede Development
I’ve had this noble desire to document my development work for a long time, but whenever I try, the first casualty always seems to be productivity.
One of the projects I’ve been working on for a while now, for example, is documentation on encoding DVDs and AVI files for iTunes/AppleTV. So far, I’ve documented my hardware setup, and the method I use for ripping and encoding DVDs, as well as tools I use to convert AVI files to compatible MP4 files. This documentation, though, only accounts for half, maybe a quarter of what I’ve implemented. I’ve got scripts for automating the converting process and moving the files back and forth between several computers, scripts for grabbing Plot, Relase Dates, Ratings and Posters from iMDB and automatically adding them to iTunes. I’ve got scripts for displaying parsing iTunes and uploading all that data to my web page, so I have remote access to view the movies in my collection.
None of this is documented yet. In fact, I find myself reluctant to continue to develop new features and new scripts because I don’t want the divide between the code and the documentation to grow any more than it already has. At the same time, the weight of the documentation is high, the desire do it is low, and the call of Oblivion is strong.
Doing nothing isn’t even a guaranteed method to preventing the Documentation Divide ((Someone make a note of the term “Documentation Divide”. If there isn’t already a phrase for this phenomenon, I want to nominate this.)) from growing. My windows system started to go south, so I was forced to buy a new computer ahead of a schedule (a shiny new Intel-basic Mac mini; I call it Cletus).
Not only does this render most of my existing documentation obsolete (or at least irrelevant), it means that my model changes from a cross-platform, Frankenstein style system running on multiple machines to an integrated application running on a single box. Development gets easier, new features are possible, and my audience goes from three people who happen to be running the same outdated, multi-cultural hardware setup as me to anyone running a halfway decent Mac. The gulf between what’s documented and what I’m running is wider than ever, and finally having the speedy new Mac I wanted probably means it will continue to grow.
… and maybe that’s the lesson here. When I started this blog, I made the slogan “The Blog is Not the Point” as a reminder to myself that this was a web log, and that my projects were more important than usage statistics, getting Dugg, or trying to generate ad revenue. That same slogan can be equally effective in reminding myself that I don’t have to wait for my blog to catch up with the code before I get back to work: the Blog is Not the Point.