If you just want the template then here you go! Otherwise, continue reading to learn more about design docs and templates.
Why you should write design documents
The most important reason to write a design doc is for your own understanding. The process of writing the design doc will undoubtedly reveal areas where your understanding is not as deep as it should be. This will lead to a better understanding of the problem and a better solution. I write blog posts for the same reason, to better understand topics that are important to me.
Design documents provide documentation of decisions. They are easy documentation to manage because they do not need to be kept up to date. Instead, they describe why a decision was made at a specific time. Design docs are useful documentation for new engineers that are starting to work on the relevant systems. Design docs can also be referenced by other future designs and in this way, the collective knowledge of the organization can be built up.
Design docs can be used to drive consensus. In my blog post Driving consensus in an engineering organization, I outline the what, why, when, and how of consensus, so I will not repeat that here. My choice of Google Docs as a design doc template allows the document to be easily copied, shared, and commented on. I also include a table at the top of the template where the participants in the consensus process can be called out with their status. You can use any design doc to drive consensus, my template just makes it easier and more explicit.
My consensus blog post gives some ideas about when consensus needs to be driven and when it does not. If consensus needs to be driven about an engineering problem, that means a design doc needs to be written. Although there are other reasons to write design docs, this is a good place to start when deciding if a design doc is necessary.
Why you should use design doc templates
Design doc templates are a place where organizational learning can be gathered. When something goes really wrong then a postmortem should be completed to understand what happened and stop it from happening again. If the issue was caused by a design problem, then the long-term solution may be to update the design doc template to make a relevant consideration more explicit (more on this in “How to use my template”).
Having standard templates to use for design docs speeds up the writing process. Proposers will not need to make decisions about what sections need to be covered. Proposers will understand over time what information is most useful to include in their design and will focus on those areas during problem research.
Having standard templates to use for design docs speeds up the review process. Reviewers can learn over time what to look for and where.
How to use my template
As a first step to use my template, make your own copy. Then start copying from your template for each design. If you run into a problem twice consider adding a section to your template. This means if you run into some security-related design issues you may want a security subsection under the Detailed Design. Be careful with being too reactionary with making edits to the template. You may want to perform a postmortem to validate that the security issue was caused by the design and not an error in implementation or something else.
Although I recommend using the table at the top of the template to manage your consensus process, this is not necessary. Writing a design doc without a consensus process will still give you good benefits in terms of improving your designs and creating documentation.
Do not become dogmatic about the design process. Although the benefits of writing design documents are significant, not all organizations recognize this. Always be cognizant of the environment and adapt accordingly.
Designing software systems should be fun! If you find yourself dreading writing an upcoming design doc then that is a sign that something is wrong. As software engineers, we like to build and create. If the design process is interfering with that enjoyment then it needs to be overhauled or even eliminated. I would rather work with happy engineers than have beautiful documentation or effective consensus processes (but please don’t make me choose). Do not be resigned to a bad design experience, step up and fix it!
In case you made it this far and still haven’t made a copy of my template here it is again, enjoy!
Leave a Reply