How to write a good software design doc

A design doc is the most useful tool for making sure the right work gets done.

The main goal 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.

• title and people 包括作者和审核者
• overview. 简单地描述项目
• context. 项目背景
• goals and non-goals. 预期结果，以及这个项目不做哪些事情
• milestones. 包括时间点和目标
• current solution. 当前的解决方案是什么。可以以user story方式呈现出来。
• proprosed solution. 也称作technical architecture.
• alternative solutions. 其他方案，对比优缺点
• monitoring and altering. 如何做监控和报警，如何从外部评估项目如何
• cross-team impact 跨团队评估影响，这个还蛮重要的，需要其他团队什么资源和配合
• discussion. 一些还不确定或者是还有争议的地方，以及未来的想法
• detailed scoping and timeline. 具体如何执行

• Write as simply as possible. Don’t try to write like the academic papers you’ve 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 words
  • Short sentences
  • Bulleted lists and/or numbered lists
  • Concrete examples, like “User Alice connects her bank account, then …”
• Add lots of charts and diagrams
• Include numbers. The 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 funny
• Do the Skeptic Test
• Do the Vacation Test. If 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.

First of all, everyone working on the project should be a part of the design process. It’s 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. （每个参与项目的人都要参与到设计过程里面来）

First of all, everyone working on the project should be a part of the design process. It’s 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.（可以尝试一些prototype code来验证想法，在编写正式代码之前）

在编写正式文档之前，最好先和有经验的工程师谈谈自己的想法，可以得到许多有价值的反馈，同时避免许多设计上的坑

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 who’s 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, don’t 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.