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

已剪辑自: https://zhuanlan.zhihu.com/p/59533572

原文链接

作为一名软件工程师，我花了很多时间阅读和编写设计文档。在研究了数百篇这样的文档之后，我发现好的文档与项目成功之间有很强的关联性。

在本文中，我尝试去说明如何才能编写好的设计文档。

本文分为4个部分：

• 为什么要写设计文档
• 设计文档中应该包含哪些内容
• 如何编写
• 流程

为什么要写设计文档

设计文档 - 也被称作技术规范 - 描述了你计划如何去解决一个问题。已经有很多文章解释了编码之前编写设计文档的重要性。所以我在这儿要说的是:

设计文档是保证正确的工作得以完成的最有用的工具。

人们一般会认为设计文档是用来告诉别人系统是怎么工作的或者作为档案留存。设计文档确实可以起到这些作用，但这些并不是最主要目标。设计文档的最主要目标是推动你去思考，去收集反馈。

作为一般性原则，如果你工作的项目需要1个人月或者以上，就需要写设计文档。但其实对于更小型的项目，编写设计文档也是有益的。

我想如果您还在阅读，那么你一定是认可设计文档的重要性。但是不同的工程团队，甚至同一团队的工程师，经常以不同的方式编写设计文档。让我们来谈谈好的设计文档的内容，风格和流程。

设计文档中应该包含哪些内容

设计文档描述了针对一个问题的解决方案。既然问题是多种多样的，那么构建设计文档的方式也是不同的。

首先应该考虑在设计文当中包含以下几个部分。

标题和人员

设计文档的标题，作者（项目的参与者），文档的审阅者（我们将在后面的『流程』部分中详细讨论），以及文档最后更新的日期。

概述

可以被公司里任何一个工程师所理解并且根据概要内容决定是否需要阅读文档的其余部分。这部分最多不超过3个章节。

背景

对于问题的描述、为什么要做这个项目、评估项目需要了解哪些内容以及如何融入到技术战略，产品战略或者是团队的季度目标中。

目标和非目标

目标应该包括

• 描述项目对于用户的影响  — 这里的用户可以是其他团队或者系统
• 明确衡量目标的指标 — 如果可以通过一个仪表盘展示和跟踪这些指标就再好不过了

明确描述哪些问题不在目标范围内也同样重要。确保所有人对于目标的理解是一致的。

里程碑

一些可衡量的检核点。你的PM以及你的经理的经理通过浏览就可以了解项目各个部分的推进情况。如果项目超过1个月，我建议你把项目拆分成多个面向用户的里程碑。

使用自然日以便考虑延迟、假期和会议等等。它看起来可能是下面这个样子：

开始时间：2018年6月7日

里程碑1 - 新系统MVP可在夜间模式下运行：2018年6月28日

里程碑2 - 下线旧系统：2018年7月4日

结束日期：新系统增加功能X，Y，Z：2018年7月14日

如果其中一些里程碑的预计结束时间（ETA）发生变化，可在后面增加[更新]部分。这样项目干系人可以很容易了解到最新的计划。

现状

除了描述当前的系统实现以外，您还应该通过概要的流程图来描述用户是如何和系统交互以及数据是怎么流转的。用户故事是完成此类工作的很好的方式。但别忘了你的系统会有很多类型的用户，每种用户都有不同的用户用例。

建议方案

这是有些人称之为技术架构的部分。首先提供一个大的方向，然后填充大量的细节。尝试通过用户故事来进行细化。这部分可以包含很多内容和图表。想象你写完这部分就跑到一个荒岛上去度假了。团队里其他工程师可以轻松的通过这部分来实现这个方案。

替代方案

除了上面的建议方案以外，你还考虑过其他代替方案么？相比来说各有什么优缺点？有没有考虑过不是自己实现而是购买第三方解决方案或者是使用开源方案来解决问题？

可测试性、监控和报警

我喜欢在设计文档中包含这部分。人们往往会跳过这些工作，认为是最后才需要考虑的。但往往由于忽略了这些，出了问题以后，人们对问题为什么发生以及如何发生的一无所知。

跨团队的影响力

方案是否会增加值班人员和运维人员的工作负担？

方案成本是多少？

是否会引起系统回归的问题？

是否会引入新的安全风险？

有什么风险和副作用？

服务支持团队如何和客户沟通？

开放性问题

任何你有疑问，不完全确定的开放性问题，如你希望读者权衡的有争议的结论，后续完善的工作等等。也就是我们常说的『已知的未知』（Known Unknowns）

详细的范围和时间表

本节主要是为参与该项目的工程师以及他们的技术主管和经理准备的。所以这段放在文档的最后。

本质上来讲，这是你计划执行项目每一部分的分解。有很多内容是关于如何准确的界定范围，你可以阅读这篇文章了解更多关于范围界定的内容。

我倾向于用文档的这个章节来跟踪项目任务。每当范围的估算发生变化的时候，我就会更新这个章节。这个更多的是我个人的偏好。

如何编写

既然谈到了好的设计文档的内容，那我们就聊聊写作风格。我保证这个和你高中的英语课可不一样。

尽可能简单

不要写的像你读到的学术论文那样。那样写是为了取悦期刊的审核员。您的文档是为了描述您的解决方案并从其他团队成员那里获得反馈而编写的。你应该使用

• 简单的单词
• 简短的句子
• 各种列表
• 具体的例子，如『用户李磊链接到自己的银行账户，然后…』

尽可能使用图和图表

图比文字更容易阅读，图表往往用来比较几个可能的选项。我用Google Drawing来制作图表。

提示：在截图下面增加一个可编辑版本的图表的链接，这样在发生变化时可以很容易的更新它。

包含数字

问题的规模往往会决定最终的方案。为了帮助评审人员了解整个问题的概况，列举出具体的数字，如数据库的行数，用户错误的数量以及这些数字如何随着使用情况扩展。还记得Big-O符号么？

试着有趣一些

设计文档不是学术论文。人们喜欢阅读有趣的东西，所以这是让读者更投入的一个好办法。但不要为了显得有趣而偏离了文档的主题。如果你和我一样，不是一个很有趣的人，Joel Spolsky给过这样的建议 — 最简单的显得有趣的方法是在进行一般性描述的地方，使用非常具体的例子。与其说『特殊利益群体』，不如说『左撇子的牛油果民』

做一轮自评

在把文档发给其他人评审之前，自己先评审一遍。你对这样的设计有什么问题和疑惑？如果有，就尽量先解决。

做一轮休假测试

加入你要休一个长假，并且没有网络，有没有团队的其他人根据这个文档可以按你的想法实现出来？正如前面说的，设计文档的主要目标不是分享知识，而是一种有效的方式来激发别人给你有用的反馈。

流程

又是讨厌的流程！设计文档可以帮你在浪费大量时间去实现一个错误的方案或者尝试去解决一个错误的问题之前获得反馈。获得好的反馈可以有很多方法，后面会写文章介绍。现在，让我们讨论下如何编写设计文档并获得反馈。

首先，参与项目的所有人都应该参与设计的过程。虽然技术主管会做出很多决定，但每个人都应该参加讨论并认同最终的决策。所以这篇文章里提到的"你"或者"你们"都是指参与项目的所有人。

其次，设计的过程不是说盯着白板天马行空的去畅想。往往需要你着手去做一些可能的原型方案。这不意味着你要在编写设计文档之前就去写生产级别的代码。不要那样做。但你必须要写一些代码去验证你的想法。为了确保你只是写一些实验性质的代码，制定一个如『原型代码永远不能被合并到主代码分支』这样的规则。

在您开始了解如何进行项目之后，你需要执行以下几个操作

1. 请你团队中经验丰富的工程师或者技术主管作为评审人。理想情况下这个人应该对要解决的问题域非常熟悉。可以买杯咖啡贿赂下:)
2. 在会议室放个白板
3. 把你要处理的问题跟这位工程师描述下。（这一步很重要，千万不要跳过）
4. 然后把你设想的实现方式解释给这位工程师，并说服他（们）。这是非常值得去做的一件事情。

这些工作甚至可以在你编写设计文档之前就做，在投入更多时间以及纠结于某个具体细节前，尽早的获得反馈。通常即便实现方法是一样的，你的评审人也可以指出你没想到的边界情况，澄清一些容易混淆的问题，以及指出你未来可能遇到的一些困难。

在你完成设计文档初稿之后，让最初的评审人再审阅一遍。在文档的标题和人员部分写上评审人的名字。这也是对评审人员的一种认可和激励。

提醒一下，对于某些设计文档考虑邀请特定的专业评审人，如SRE工程师和安全工程师

你和评审人的工作结束之后，就可以把设计文档发送给你的团队以获得更多的反馈以及知识共享。我建议收集反馈的时间限定在1周以避免拖延。承诺在问题和评论提出的当周给予回复。如果不能及时给予反馈会造成很糟糕的后果。

最后，如果你，评审人和其他的工程师对于文档存在很多争议，我强烈建议把所有的争论点放在文档的"讨论"部分。然后召开会议和各方讨论这些分歧。

如果某个讨论的主题有超过5条评论，那么改成面对面的讨论会更有效率。记住即使最终无法达成共识，你仍有责任做出最后的决定。

最近在和Shrey Banga谈到这个时，我了解到Quip有类似的流程，除了找一个有经验的工程师或者技术主管作为评审人外，他们还建议邀请一个其他团队的工程师审阅这个文档。我虽然没有尝试过，但从不同角度收集反馈明显是有益的，同时也能改进文档的可读性。

完成上面所有这一切以后，就可以撸起袖子干活了。额外一点，要记得保持文档的更新。无论是工作范围或者方案的修改，都同步更新这个文档。这样你就不用一遍遍去跟别人解释这些问题。

最后让我们了解下如何评估一份文档是否成功？

我的同事Kent Rakip 对此有一个很好的答案：如果该项工作的投入产出比（ROI）是合适的，那么设计文档就是成功的。这意味着成功的设计文档实际上会导致这样的结果：

1. 您花了5天时间编写设计文档，这迫使你从不同的方面考虑技术架构
2. 你从评审人员那里得到一些反馈，如X是建议的架构中风险最高的部分
3. 你决定首先实施X，降低项目风险
4. 3天后你发现X要么是不可行的，要么比原先设想的困难的多
5. 你决定停止这个项目，优先处理其他工作

在文章的开头，我们说过设计文档的目标是确保做正确的事情。在上面的例子中，由于有了设计文档，你只花了8天时间，而不是浪费几个月时间才去中止这个项目。这对我来说是非常好的一个结果。