Automate Your Documentation
Editorial Note: I originally wrote this post for the SmartBear blog.
Few things, I’d say, strike boredom into the developer heart faster than the subject of documentation. Does anyone out there really just love wrapping up development on a feature and then cranking out a Word document with a bunch of screen shots and step by step instructions. Or, perhaps you fancy the excitement of pasting a legal header above a class you’ve just written, and then laboriously documenting all of methods, variables, and function parameters in the class? If not that, how about the thrill of going back and updating comments that no longer make sense after the code has changed?
I suspect I don’t have a lot of takers at this point.
Documentation is boring, at least for the overwhelming majority of us. After you’ve built a thing, you want to go build another thing — not rehash in laborious detail what you just did. And yet, documentation is essential for communicating across time and teams to other people. Your users will need documentation. Future maintenance programmers need documentation. Unless you’re going to be around in perpetuity to handle all that comes, you need to leave some sort of persistent knowledge transfer vehicle.
But that doesn’t mean it has to be tedious, repetitive, or boring.
Repetitive labor offers a certain counter-intuitive appeal, since it creates a “pain is gain” feeling of diligence and accomplishment when complete But don’t be fooled. People make many sloppy mistakes when doing repetitive tasks and drudgery is a terrible use of company money when you’re collecting a salary as a knowledge worker. As people in the software industry, we earn a living automating grunt work out of existence, so let’s take a look at how we can help ourselves when it comes to documentation.