As a software engineer, I spend a lot of time reading and writing design documents. After having gone through hundreds of these docs, I’ve 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 document
- What to include in a design document
- How to write it
- The process around it
Why 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 it’s important to write a design doc before diving into coding. So all I’ll 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 don’t 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 let’s talk about the content, style, and process of a good design doc.