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.
If you’re anything like me in your programming proclivities, there’s a kind of singular impatience that leaps into your mind around the subject of documentation. On the consuming side, whether it’s an API or a product, you have a tendency to think to yourself, “I don’t want to read about it, I just want to start hacking away at it.” On the flip side, when it comes to producing documentation, that seems an onerous process; you’ve already finished the work, so why belabor the point?
Those are my natural impulses, but I do recognize the necessity for producing and consuming documentation surrounding the work that we do. Over the years, I’ve developed strategies for making sure I get it done when it needs to be done. For instance, even as someone who makes part of my living writing and teaching, I still segment my days for the sake of efficiency; I have writing days and I have programming days.
In order for this work not to get shortchanged in your group, it’s important to develop similar strategies or commitment devices. The work needs to get done, and it needs to get done well, or else it won’t be useful. And peer review is a vital part of that process. After all, you create process around peer review for code — the developers’ strategy for sanity checks and spreading of knowledge. Doesn’t it stand to reason that you should also do this with the documents that you create around this process?
Let’s take a look at some documentation that your group may be producing, and explore the idea of having peer review to go along with it. We’ll look at an answer to the question, “what technical documents should you review?”