A Guide to Software Design Documents and Design Reviews

If you’re a new software engineer (or maybe even if you aren’t), you might dread design docs, and you might even despise those asking for them. The first time I was asked to write one, I had no idea why, or any idea what to put in it. I pieced it from a couple other design docs I found in my company’s wiki hoping it would satisfy my manager’s request. Good enough! But the next few documents after that presented merely a marginal improvement on this shaky foundation, and the initial dread never really went away. Then I joined a team that had a template for their docs, and I thought why can’t every team have that, like they have clear coding standards? It didn’t do everything to alleviate the weight of writing them, but it was a great start.

Here I’m going try to give a sort-of complete guide where I’ll attempt to explain what design documents are useful for, what they should contain, and how to get the most effective feedback from design reviews. My goal is to simplify them so that they can become a useful tool in your work.

Why Should We Write Design Docs?

Simply put, writing is the best way to clarify your thinking.

It might feel at first like design docs are just a way to get more senior engineers to approve your upcoming work, but there is value in…