How to write a good software design doc

As a software engineer, I spend a lot of time reading and writing design documents. After having gone through hundreds of these docs, Ive seen first hand a strong correlation between good design docs and the ultimate success of the project.This article is my attempt at describing what makes a design document great.

The article is split into 4 sections:Why write a design documentWhat to include in a design documentHow to write itThe process around itWhy write a design document?A design doc also known as a technical spec is a description of how you plan to solve a problem.There are lots of writings already on why its important to write a design doc before diving into coding.

So all Ill say here is:A design doc is the most useful tool for making sure the right work gets done. The main goal of a design doc is to make you more effective by forcing you to think through the design and gather feedback from others. People often think the point of a design doc is to to teach others about some system or serve as documentation later on.

While those can be beneficial side effects, they are not the goal in and of themselves. As a general rule of thumb, if you are working on a project that might take 1 engineer-month or more, you should write a design doc. But dont stop there a lot of smaller projects could benefit from a mini design doc too.

Great! If you are still reading, you believe in the importance of design docs. However, different engineering teams, and even engineers within the same team, often write design docs very differently.

So lets talk about the content, style, and process of a good design doc.What to include in a design doc?A design doc describes the solution to a problem.

Since the nature of each problem is different, naturally youd want to structure your design doc differently.To start, the following is a list of sections that you should at least consider including in your next design doc:Title and PeopleThe title of your design doc, the author(s) (should be the same as the list of people planning to work on this project), the reviewer(s) of the doc (well talk more about that in the Process section below), and the date this document was last updated.OverviewA high level summary that every engineer at the company should understand and use to decide if its useful for them to read the rest of the doc.

It should be 3 paragraphs max. ContextA description of the problem at hand, why this project is necessary, what people need to know to assess this project, and how it fits into the technical strategy, product strategy, or the teams quarterly goals.Goals and Non-GoalsThe Goals section should:describe the user-driven impact of your project where your user might be another engineering team or even another technical systemspecify how to measure success using metrics bonus points if you can link to a dashboard that tracks those metricsNon-Goals are equally important to describe which problems you wont be fixing so everyone is on the same page.

MilestonesA list of measurable checkpoints, so your PM and your managers manager can skim it and know roughly when different parts of the project will be done. I encourage you to break the project down into major user-facing milestones if the project is more than 1 month long.Use calendar dates so you take into account unrelated delays, vacations, meetings, and so on.

It should look something like this:Start Date: June 7, 2018Milestone 1 New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018Add an [Update] subsection here if the ETA of some of these milestone changes, so the stakeholders can easily see the most up-to-date estimates. Existing SolutionIn addition to describing the current implementation, you should also walk through a high level example flow to illustrate how users interact with this system and/or how data flow through it.A user story is a great way to frame this.

Keep in mind that your system might have different types of users with different use cases. Proposed SolutionSome people call this the Technical Architecture section. Again, try to walk through a user story to concretize this.

Feel free to include many sub-sections and diagrams. Provide a big picture first, then fill in lots of details. Aim for a world where you can write this, then take a vacation on some deserted island, and another engineer on the team can just read it and implement the solution as you described.

Alternative SolutionsWhat else did you consider when coming up with the solution above? What are the pros and cons of the alternatives? Have you considered buying a 3rd-party solution or using an open source one that solves this problem as opposed to building your own?

Testability, Monitoring and AlertingI like including this section, because people often treat this as an afterthought or skip it all together, and it almost always comes back to bite them later when things break and they have no idea how or why. Cross-Team ImpactHow will this increase on call and dev-ops burden? How much money will it cost?

Does it cause any latency regression to the system? Does it expose any security vulnerabilities? What are some negative consequences and side effects?

How might the support team communicate this to the customers?Open QuestionsAny open issues that you arent sure about, contentious decisions that youd like readers to weigh in on, suggested future work, and so on. A tongue-in-cheek name for this section is the known unknowns.

Detailed Scoping and TimelineThis section is mostly going to be read only by the engineers working on this project, their tech leads, and their managers. Hence this section is at the end of the doc.Essentially, this is the breakdown of how and when you plan on executing each part of the project.

Theres a lot that goes into scoping accurately, so you can read this post to learn more about scoping. I tend to also treat this section of the design doc as an ongoing project task tracker, so I update this whenever my scoping estimate changes. But thats more of a personal preference.

How to write itNow that weve talked about what goes into a good design doc, lets talk about the style of writing. I promise this is different than your high school English class.Write as simply as possibleDont try to write like the academic papers youve read.

They are written to impress journal reviewers. Your doc is written to describe your solution and get feedback from your teammates. You can achieve clarity by using:Simple wordsShort sentencesBulleted lists and/or numbered listsConcrete examples, like User Alice connects her bank account, then Add lots of charts and diagramsCharts can often be useful to compare several potential options, and diagrams are generally easier to parse than text.

Ive had good luck with Google Drawing for creating diagrams. Pro Tip: remember to add a link to the editable version of the diagram under the screenshot, so you can easily update it later when things inevitably change.Include numbersThe scale of the problem often determines the solution.

To help reviewers get a sense of the state of the world, include real numbers like # of DB rows, # of user errors, latency and how these scale with usage. Remember your Big-O notations?Try to be funnyA spec is not an academic paper.

Also, people like reading funny things, so this is a good way to keep the reader engaged. Dont overdo this to the point of taking away from the core idea though. If you, like me, have trouble being funny, Joel Spolsky (obviously known for his comedic talents) has this tip:One of the easiest ways to be funny is to be specific when its not called for [ Example:] Instead of saying special interests, say left-handed avacado farmers.

Do the Skeptic TestBefore sending your design doc to others to review, take a pass at it pretending to be the reviewer. What questions and doubts might you have about this design? Then address them preemptively.

Do the Vacation TestIf you go on a long vacation now with no internet access, can someone on your team read the doc and implement it as you intended?The main goal of a design doc is not knowledge sharing, but this is a good way to evaluate for clarity so that others can actually give you useful feedback.ProcessAh yes, the dreaded P-word.

Design docs help you get feedback before you waste a bunch of time implementing the wrong solution or the solution to the wrong problem. Theres a lot of art to getting good feedback, but thats for a later article. For now, lets just talk specifically about how to write the design doc and get feedback for it.

First of all, everyone working on the project should be a part of the design process. Its okay if the tech lead ends up driving a lot of the decisions, but everyone should be involved in the discussion and buy into the design. So the you throughout this article is a really plural you that includes all the people on the project.

Secondly, the design process doesnt mean you staring at the whiteboard theorizing ideas. Feel free to get your hands dirty and prototype potential solutions. This is not the same as starting to write production code for the project before writing a design doc.

Dont do that. But you absolutely should feel free to write some hacky throwaway code to validate an idea. To ensure that you only write exploratory code, make it a rule that none of this prototype code gets merged to master.

After that, as you start to have some idea of how to go about your project, do the following:Ask an experienced engineer or tech lead on your team to be your reviewer. Ideally this would be someone whos well respected and/or familiar with the edge cases of the problem. Bribe them with boba if necessary.

Go into a conference room with a whiteboard. Describe the problem that you are tackling to this engineer (this is a very important step, dont skip it!).

Then explain the implementation you have in mind, and convince them this is the right thing to build.Doing all of this before you even start writing your design doc lets you get feedback as soon as possible, before you invest more time and get attached to any specific solution. Often, even if the implementation stays the same, your reviewer is able to point out corner cases you need to cover, indicate any potential areas of confusion, and anticipate difficulties you might encounter later on.

Then, after youve written a rough draft of your design doc, get the same reviewer to read through it again, and rubber stamp it by adding their name as the reviewer in the Title and People section of the design doc. This creates additional incentive and accountability for the reviewer. On that note, consider adding specialized reviewers (such as SREs and security engineers) for specific aspects of the design.

Once you and the reviewer(s) sign off, feel free to send the design doc to your team for additional feedback and knowledge sharing. I suggest time-bounding this feedback gathering process to about 1 week to avoid extended delays. Commit to addressing all questions and comments people leave within that week.

Leaving comments hanging = bad karma.Lastly, if theres a lot of contention between you, your reviewer, and other engineers reading the doc, I strongly recommend consolidating all the points of contention in the Discussion section of your doc. Then, set up a meeting with the different parties to talk about these disagreements in person.

Whenever a discussion thread is more than 5 comments long, moving to an in-person discussion tends to be far more efficient. Keep in mind that you are still responsible for making the final call, even if everyone cant come to a consensus.In talking to Shrey Banga recently about this, I learned that Quip has a similar process, except in addition to having an experienced engineer or tech lead on your team as a reviewer, they also suggest having an engineer on a different team review the doc.

I havent tried this, but I can certainly see this helping get feedback from people with different perspectives and improve the general readability of the doc.Once youve done all the above, time to get going on the implementation! For extra brownie points, treat this design doc as a living document as you implement the design.

Update the doc every time you learn something that leads to you making changes to the original solution or update your scoping. Youll thank me later when you dont have to explain things over and over again to all your stakeholders.Finally, lets get really meta for a second: How do we evaluate the success of a design doc?

My coworker Kent Rakip has a good answer to this: A design doc is successful if the right ROI of work is done. That means a successful design doc might actually lead to an outcome like this:You spend 5 days writing the design doc, this forces you to think through different parts of the technical architectureYou get feedback from reviewers that X is the riskiest part of the proposed architectureYou decide to implement X first to de-risk the project3 days later, you figure out that X is either not possible, or far more difficult than you originally intendedYou decide to stop working on this project and prioritize other work insteadAt the beginning of this article, we said the goal of a design doc is to make sure the right work gets done. In the example above, thanks to this design doc, instead of wasting potentially months only to abort this project later, youve only spent 8 days.

Seems like a pretty successful outcome to me.So you got added as a reviewer of a spec, what should you do?My good friend and role model Joy has the follow excellent tips:By the time you sign off on a spec, you should understand the answers to the following.

ProjectWhat problem is this project solving? How will we know when its successful?MetaWhat are the biggest decisions this project is making?

What are the implications?What is the most complex or risky piece of the project? How is that handled?

Technical designWhat is the simplest alternative implementation you can think of in 5 minutes? What are the pros/cons of the proposed approach relative to this? What improvements is the extra implementation time in the proposed approach buying?

Is it worth it? Note: this does not mean to imply youre going to come up with a better approach in 5 minutes. Its just to give you something more concrete to compare the proposed implementation against.

What are the key technical decisions in this project? What are the tradeoffs being made as a result of these decisions?What external systems does this project interact with?

How much scale is it adding? Does it follow current best practices and patterns? Does it fit into the long-term direction?

Does it imply future commitments or tech debt?What is information that youre aware of which the writer may not have known? Have you seen a similar solution used before?

(successful or not) Are there non-obvious edge cases in systems theyre working with? Is there a piece of straightforward implementation that you think will actually take a while?Monitoring/alertingWhat is the most likely failure mode during the project (e.

g. mid-rollout)What is the most likely failure mode after the project?How will the above be monitored and detected?

Please leave a comment below if you have any questions or feedback! Id also love to hear about how you do design docs differently in your team.Giving credit where credit is due, I learned a lot of the above by working alongside some incredible engineers at Plaid (we are hiring!

Come design and build some sweet technical systems with us) and Quora.If you like this post, follow me on Twitter for more posts on engineering, processes, and backend systems.