Editorial Note: I originally wrote this post for the SmartBear blog. You can check out the original here, at their site. While you’re there, have a look at the posts by some of the other authors.
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?”