In Silicon Valley, if you randomly stop a programmer on the street and ask, “Before starting a project, what should you do?” nine out of ten will likely answer, “Write a design doc.” So, why are design docs so important? Let’s start by defining what a design doc is.
A design document (design doc) is a shared file among engineers that describes a feature to be implemented before any code is written, like in
- Overview: A few simple sentences describing the feature to be implemented.
- Motivation: Why are we implementing this feature?
- Preview: What will the feature look like after it’s implemented?
- Technical Choices: What technical options do we have to implement this feature? What are the pros and cons of each? Which one did we choose and why?
- Necessary Implementation Details: List code templates, how to test, how to write logs, etc. It’s important to note that a design document should remain high-level; the specific implementation is the job of the code.
A primary author drafts the design document, and their colleagues communicate with the author by commenting on the document. This entire communication process often lasts for several days or even weeks. Once the author and colleagues agree on the content of the document, it can be merged into the codebase. This also marks the beginning of the project described in the design document.
This process of incorporating design documents into projects offers numerous benefits.
First, design documents help you clarify your thoughts. If you can articulate your ideas in concise, logically clear language, it indicates a deep understanding of the feature’s implementation. Conversely, if you can’t even express what you intend to write, then implementing the feature will be even harder. Your colleagues, by commenting on your design document, will also help you review your ideas, discover problems in advance, point out logical flaws, and even suggest better implementation methods (I’ve repeatedly found that colleagues around me consistently come up with better solutions and identify logical gaps in my thinking). Especially experienced programmers on the team can save you a significant amount of development time later on with simple suggestions.
Second, design documents help the entire team reach a consensus. They make everyone’s technical thinking transparent, and the codebase becomes more maintainable. If a design document is approved by everyone, then everyone will have more ownership of the entire project and be more willing to help improve code quality, leading to high overall engineering quality for the project.
Third, design documents are an excellent supplement to code. New team members and colleagues from other teams can easily gain a high-level understanding of the entire codebase through design documents. When someone wants to understand the project’s status, there’s nothing more satisfying than just sending them a link.
Fourth, design documents help teams save time. Compared to lengthy meetings, design documents allow colleagues (in different time zones) to calmly reflect independently at their own suitable time, refine their thoughts, and provide feedback to the author. Pre-development discussions among colleagues can effectively review the entire design approach, significantly reducing the risk of flawed designs (believe me, I’ve more than once been lazy and directly wrote code, only to find days of my development proved useless). During development, since colleagues already understand the design concept, code reviews become simpler. If issues arise during pre-development, developers can also more easily get help from colleagues. After development, design documents also provide a basis for the entire team to conduct technical post-mortems.
Fifth, design documents are excellent for organizing teams. Colleagues who participate in discussions are often those interested in the problem the design document aims to solve. Through design documents, they can quickly form small teams and complete tasks efficiently with sufficient passion.
Sixth, design documents are excellent material for promotion. Design documents often reflect the author’s engineering literacy, clarity of thought in problem-solving, and ability to solve important problems.
Since writing design documents brings so many benefits to a team, why doesn’t everyone follow this practice? From my observations, it might be due to the following misconceptions:
- “Writing design documents is too much trouble, maybe I’ll just start coding first?” If you find design documents difficult to write, it indicates that the author doesn’t understand the problem thoroughly enough, and their chosen implementation method is likely incorrect. Writing design documents certainly requires a lot of effort initially, but as mentioned above, these investments are valuable in the long run.
- “If I skip writing the document, I’d have finished the code already.” Everything in moderation. Whether a design document is needed depends on the project’s long-term code quality and maintainability. If a feature is easy to implement and its logic is straightforward, perhaps simply creating an issue to describe the feature would suffice, and code maintenance and team alignment can be achieved through code reviews. However, for complex features, writing a design document is still recommended.
- “I’m good at this, watch me implement it directly and impress my colleagues.” While having areas of expertise is a plus, communication within the team is equally important. On one hand, if colleagues don’t understand the author’s approach, it’s difficult for them to conduct code reviews; on the other hand, the code maintainer and the author are often not the same person. If the author’s ideas aren’t preserved through documentation, and the code is complex, the maintainability of the entire project will decline.
Strive to change these perceptions, step out of your comfort zone, try to start writing design documents, and actively participate in commenting on others’ design documents. You’ll find that your contributions to the team will multiply.
Anecdote: I once complained to a colleague, “I really can’t understand other people’s code, especially in languages like Python, which are easy to write but hard to read.” The colleague replied, “Don’t worry, they can’t understand yours either.” I laughed then, thinking: if there were no design documents to keep everyone aligned at a high level, and everyone only communicated by reading each other’s code, how inefficient would the team’s operations be?
