如何编写好的软件设计文档

by Angela Zhang

通过张韶涵

如何编写好的软件设计文档 (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, 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:

本文分为4个部分：

• 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.

根据一般经验，如果您从事的项目可能需要1个工程师月甚至更多的工时，则应编写设计文档。 但是不要到此为止-小型设计文档也可以使很多较小的项目受益。

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.

大！ 如果您仍在阅读，则相信设计文档的重要性。 但是，不同的工程团队，甚至是同一团队中的工程师，通常在编写设计文档时也会大相径庭。 因此，让我们讨论一个好的设计文档的内容，样式和过程。

设计文档中要包含什么？ (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 you’d 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 People)

The 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 (we’ll talk more about that in the Process section below), and the date this document was last updated.

设计文档的标题 作者(应与计划从事此项目的人员列表相同)，审稿人 文档的名称(我们将在下面的“处理”部分中详细讨论)，以及该文档的最后更新日期。

总览 (Overview)

A high level summary that every engineer at the company should understand and use to decide if it’s useful for them to read the rest of the doc. It should be 3 paragraphs max.

公司的每位工程师都应理解并使用的高级摘要，以决定对他们阅读其余文档是否有用。 最多3个段落。

语境 (Context)

A 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 team’s quarterly goals.

描述当前的问题，为什么需要这个项目，人们需要知道什么来评估这个项目以及它如何适合技术策略，产品策略或团队的季度目标。

目标与非目标 (Goals and Non-Goals)

The Goals section should:

目标部分应：

• describe the user-driven impact of your project — where your user might be another engineering team or even another technical system
  描述您的项目对用户的影响-您的用户可能是另一个工程团队甚至另一个技术系统
• specify how to measure success using metrics — bonus points if you can link to a dashboard that tracks those metrics
  指定如何使用指标来衡量成功-如果您可以链接到跟踪那些指标的仪表板，则可以获得加分

Non-Goals are equally important to describe which problems you won’t be fixing so everyone is on the same page.

非目标对于描述您不会解决的问题同样重要，因此每个人都在同一页面上。

大事记 (Milestones)

A list of measurable checkpoints, so your PM and your manager’s 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.

可测量检查点的列表，因此您的项目经理和经理的经理可以略过这些检查点，并大致了解何时完成项目的不同部分。 如果项目超过1个月，建议您将项目分解为主要的面向用户的里程碑。

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, 2018

Start Date: June 7, 2018 Milestone 1 — New system MVP running in dark-mode: June 28, 2018 Milestone 2 - Retire old system: July 4th, 2018 End Date: Add feature X, Y, Z to new system: July 14th, 2018

Add 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.

如果其中一些里程碑的预计到达时间发生了变化，请在此处添加[Update]小节，以便利益相关者可以轻松查看最新估计。

现有解决方案 (Existing Solution)

In 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 Solution)

Some 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 Solutions)

What 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 Alerting)

I 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 Impact)

How 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 Questions)

Any open issues that you aren’t sure about, contentious decisions that you’d 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 Timeline)

This 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. There’s 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 that’s more of a personal preference.

我也倾向于将设计文档的这一部分视为正在进行的项目任务跟踪程序，因此只要我的范围估算值发生变化，我都会对其进行更新。 但这更多是个人喜好。

怎么写 (How to write it)

Now that we’ve talked about what goes into a good design doc, let’s talk about the style of writing. I promise this is different than your high school English class.

现在，我们已经谈到了进入一个好的设计文档，让我们来谈谈写作风格。 我保证这与您的高中英语课不同。

尽可能简单地写 (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 …”
  具体示例，例如“用户Alice连接她的银行帐户，然后…”

添加大量图表 (Add lots of charts and diagrams)

Charts can often be useful to compare several potential options, and diagrams are generally easier to parse than text. I’ve had good luck with Google Drawing for creating diagrams.

图表通常可用于比较多个潜在选项，并且图表通常比文本更易于解析。 我对使用Google绘图创建图表感到很幸运。

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 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?

问题的规模通常决定解决方案。 为了帮助审阅者了解世界的状况，请包括实数，例如数据库行数，用户错误数，延迟，以及它们如何随使用情况扩展。 还记得您的Big-O符号吗？

尝试变得有趣 (Try to be funny)

A spec is not an academic paper. Also, people like reading funny things, so this is a good way to keep the reader engaged. Don’t 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:

如果您像我一样在幽默方面遇到麻烦， 乔尔·斯波斯基 ( Joel Spolsky) ( 显然以喜剧天赋而闻名……)提供了以下提示：

One of the easiest ways to be funny is to be specific when it’s not called for [… Example:] Instead of saying “special interests,” say “left-handed avacado farmers.”

最简单的有趣方法之一是在不要求使用时加以具体说明 。[...示例：]不用说“特殊利益”，而要说“左撇子农民”。

做怀疑测试 (Do the Skeptic Test)

Before 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 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.

设计文档的主要目标不是知识共享，但这是评估清晰度的一种好方法，这样其他人才能真正为您提供有用的反馈。

处理 (Process)

Ah 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. There’s a lot of art to getting good feedback, but that’s for a later article. For now, let’s just talk specifically about how to write the design doc and get feedback for it.

是的，可怕的P字 。 设计文档可帮助您在浪费大量时间实施错误的解决方案或错误的解决方案之前获得反馈。 获得良好的反馈有很多技巧，但这是在以后的文章中。 现在，让我们仅具体讨论如何编写设计文档并获取反馈。

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.

首先，每个从事项目工作的人都应该参与设计过程。 技术领导最终做出很多决定是可以的，但是每个人都应参与讨论并加入设计。 因此，本文中的“您”是一个真正的复数“您”，其中包括项目中的所有人员。

Secondly, the design process doesn’t 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. Don’t 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.

其次，设计过程并不意味着您盯着白板的理论构想。 随时动手动手，为潜在的解决方案提供原型。 这与在编写设计文档之前开始为项目编写生产代码不同。 不要那样做 但是，您绝对应该随意编写一些简单易用的代码来验证一个想法。 为了确保您只编写探索性代码，请遵循以下规则：所有原型代码都不会合并到master 。

After that, as you start to have some idea of how to go about your project, do the following:

之后，当您开始对如何进行项目有所了解时，请执行以下操作：

1. 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.
   请您团队中经验丰富的工程师或技术负责人作为您的审阅者。 理想情况下，这将是一个受人尊敬和/或熟悉问题边缘情况的人。 必要时用boba贿赂它们。
2. Go into a conference room with a whiteboard.
   进入带有白板的会议室。

3. Describe the problem that you are tackling to this engineer (this is a very important step, don’t skip it!).

   描述您要解决的问题 (这是非常重要的一步，请不要跳过！)。

4. 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 you’ve 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.

关于这一点，请考虑为设计的特定方面添加专门的审阅者(例如SRE和安全工程师)。

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.

一旦您和审阅者签名，就可以将设计文档发送给您的团队以获取其他反馈和知识共享。 我建议将此反馈收集过程的时间限制为大约1周，以避免长时间的延迟。 致力于解决人们在一周内留下的所有问题和评论。 留下评论=业障。

Lastly, if there’s 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 can’t come to a consensus.

每当讨论线程的长度超过5条评论时，进行面对面的讨论往往会更有效率。 请记住，即使每个人都无法达成共识，您仍然要对最终决定负责。

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 haven’t tried this, but I can certainly see this helping get feedback from people with different perspectives and improve the general readability of the doc.

在最近与Shrey Banga交谈时，我了解到Quip的过程类似，除了在团队中拥有经验丰富的工程师或技术负责人作为审阅者外，他们还建议让其他团队的工程师对文档进行审阅。 我没有尝试过，但是我可以肯定地看到这有助于从不同角度获得人们的反馈，并提高文档的总体可读性。

Once you’ve 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. You’ll thank me later when you don’t have to explain things over and over again to all your stakeholders.

完成上述所有操作后，就可以开始实施了！ 要获得额外的布朗尼点， 请在实施设计时将此设计文档视为有效文档 。 每次您学习到可导致您更改原始解决方案或更新范围的知识时，请更新文档。 当您不必一遍又一遍地向所有利益相关者解释事情时，您会感谢我。

Finally, let’s 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:

我的同事肯特·拉基普(Kent Rakip)对此有一个很好的回答： 如果完成了正确的工作ROI，则设计文档将成功。 这意味着成功的设计文档实际上可能会导致如下结果：

1. You spend 5 days writing the design doc, this forces you to think through different parts of the technical architecture
   您花了5天的时间编写设计文档，这迫使您仔细考虑技术体系结构的不同部分

2. You get feedback from reviewers that X is the riskiest part of the proposed architecture

   您会收到来自审阅者的反馈，认为X是建议架构中最危险的部分

3. You decide to implement X first to de-risk the project

   您决定先实施X以降低项目风险

4. 3 days later, you figure out that X is either not possible, or far more difficult than you originally intended

   3天后，您发现X不可能或比您原本打算的困难得多

5. You decide to stop working on this project and prioritize other work instead
   您决定停止从事该项目，并优先处理其他工作

At 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, you’ve only spent 8 days. Seems like a pretty successful outcome to me.

在本文开头，我们说过设计文档的目标是确保正确完成工作。 在上面的示例中，由于有了此设计文档，您才花了8天的时间，而不会浪费可能要几个月才能中止该项目的时间。 对我来说似乎是一个非常成功的结果。

Please leave a comment below if you have any questions or feedback! I’d 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.

在应得的荣誉中给予荣誉，我与Plaid的一些不可思议的工程师( 我们正在招聘！与我们一起设计并构建一些实用的技术系统)和Quora一起学习了很多上述知识。

If you like this post, follow me on Twitter for more posts on engineering, processes, and backend systems.

如果您喜欢这篇文章，请在Twitter上关注我，以获取有关工程，流程和后端系统的更多文章。

翻译自: https://www.freecodecamp.org/news/how-to-write-a-good-software-design-document-66fcf019569c/