How to Write an Effective Software Design Document · Refactoring EnglishA good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner. It’s also the best way to coordinate design decisions among teammates and partner teams.<br>I’ve written design docs as a developer at Google, Microsoft, and within my own companies. The specifics vary, but the underlying principles remain the same. A design doc should articulate the hard problems you’re solving and help your teammates give you feedback.<br>Below, I share my approach to creating effective design docs and explain what belongs in a design doc and what does not.<br>An example design doc<br>When should you write a design doc?<br>How much should you invest into your design doc?<br>What belongs in a design doc?What’s the cost of getting it wrong?
Components of a design docTitle<br>Metadata<br>Objective<br>Background<br>Related documents<br>Goals<br>Non-goals<br>Scenarios<br>Diagrams<br>Glossary<br>Constraints<br>Service level objectives (SLOs)<br>Monitoring / alerting<br>Timeline<br>Interfaces<br>Dependencies / infrastructure<br>Security<br>Privacy<br>Legal considerations<br>Logging<br>Open issues<br>Resolved issues<br>Alternatives considered
Driving Your Design Doc through Review<br>An example design doc🔗<br>The most common question I get about design docs is where to find a good one. I’ve never seen a public design doc that I consider high-quality. All of mine are hidden away at the companies that paid me to write them.<br>So, I wrote a design doc from scratch based on the principles I’m sharing here. It lays out the design for a real web app I’m building.
Your browser does not support the video tag.I created the design doc before writing any code, and I’m adhering to the design as I implement the app.<br>Little Moments Design Doc<br>The design is more exhaustive than what I’d normally write for a solo hobby project, but this is roughly the length and depth of a design doc I’d create if I were coordinating work with other people on a professional project.<br>When should you write a design doc?🔗<br>The more complex or risky the project, the more valuable it is to write a design doc.<br>Consider these questions:<br>Will multiple people coordinate work to implement the design?<br>Will the project take more than three months of full-time dev work?<br>Will the implementation run in production for several years?<br>Does the project involve cross-team collaboration?<br>Are the goals and requirements of the project ambiguous?<br>Are there catastrophic risks you could prevent at design time (e.g., security flaws, legal risks)?<br>If you answered “yes” to any of these questions, then it’s likely worth the effort to write a design doc. If you answered “yes” to two or more, a design doc will almost certainly be worth the effort.<br>How much should you invest into your design doc?🔗<br>A design doc can be a simple one-pager or a 50-page document that requires signoff from five different teams. You need to decide how much detail makes sense.<br>There’s no universal rule that says how long you should spend on a design doc just like there’s no rule that says how much to test your code. The right investment depends on your team’s goals, risks, deadlines, and culture. Sometimes, the right amount to invest in a design doc is zero.<br>What belongs in a design doc?🔗<br>If you specify every possible detail in a design doc, you’ve essentially written the implementation during the design phase. That would defeat the whole purpose of a design doc.<br>As a rule of thumb, you can ask a simple question to decide whether a decision belongs in your design doc: what’s the penalty for being wrong?<br>What’s the cost of getting it wrong?🔗<br>Not all design decisions are equally important. Some choices are radically more flexible than others.<br>For example, if you build a web application in C++ and realize 200k lines later that Ruby on Rails was the better choice, you’re stuck. A from-scratch rewrite would never work, and even if you manage to write new code in Rails, you still suffer the burden of maintaining code in two wildly different languages.<br>Other design decisions are trivial. For example, if your app displays a list of 1,000 articles, should they all appear at once? Or should the user see 20 at a time and click “Load more” to see the next 20?<br>It doesn’t matter.<br>A “load more” button is not a design-level concern. If you pick one solution, and user feedback tells you you’re wrong, you can fix it in a few hours. You don’t need to detail your entire thought process in your design doc, and you definitely shouldn’t waste review cycles arguing about it.<br>Components of a design doc🔗<br>Below, I’ve included common sections to include in your design docs. You generally don’t need every single section for every...