如何写出一份优秀的软件设计文档

作为一名软件工程师，我花了很多时间阅读和编写设计文档。在完成了数百篇这些文档之后，我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联。

本文试图描述什么使设计文档变得更好。

本文分为4个部分：

· 为什么要写一份设计文档

· 要包含在设计文档中的内容

· 怎么写

· 相关过程

为什么要写一个设计文档？
设计文档 - 也称为技术规范 - 描述了您计划如何解决问题。

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

设计文档的主要目标是通过强迫您思考设计并收集其他人的反馈来提高您的效率。人们通常认为设计文档的目的是教会其他人关于某个系统或稍后作为文档。虽然这些可能是一部分作用，但它们并不是最根本的目的。

作为一般经验法则，如果您正在处理可能需要1个工程师月或更长时间的项目，那么您应该编写设计文档。但不要止步于此 - 许多小型项目也可以从迷你设计文档中受益。

如果您还在阅读，您会相信设计文档的重要性。但是，不同的研发团队，甚至同一团队的工程师，经常以非常不同的方式编写设计文档。让我们来谈谈优秀设计文档的内容，风格和写作流程吧。

设计文档中应该包含哪些内容？
设计文档描述了问题的解决方案。由于每个问题的性质不同，您自然希望以不同的方式构建您的设计文档。

首先，以下是您应该至少考虑在下一个设计文档中包含的部分列表：

标题和参与者
您的设计文档的标题，作者（应该与计划参与此项目的人员列表相同），检查者（我们将在“处理”部分中详细讨论），以及最后更新日期。

概览
高度概括的，公司的每位工程师都应该理解并能够通过阅读概览来决定是否有必要阅读其余的文档。最多3段。

背景
对手头问题的描述，为什么这个项目是必要的，人们需要知道什么来评估这个项目，以及它如何适应技术战略，产品战略或团队的季度目标。

目标和非目标
目标部分应包括：

描述项目的用户驱动影响 - 您的用户可能是另一个工程团队甚至是另一个技术系统
指定如何使用指标衡量成功 - 如果您可以链接到跟踪这些指标的仪表板，则可以获得奖励
非目标同样重要，它描述了您不会修复哪些问题，因此它也和目标在同一页面上。

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

使用日历日期，以便考虑无关的延迟，假期，会议等。它应该看起来像这样：

开始日期：2018年6月7日
里程碑1 - 以暗模式运行的新系统MVP：2018年6月28日
里程碑2 - 下掉旧系统：2018年7月4日
结束日期：将功能X，Y，Z添加到新系统：2018年7月14日

如果其中一些里程碑的ETA发生变化，请在此处添加[更新]子部分，以便相关方可以轻松查看最新的情况。

当前解决方案
除了描述当前的实现之外，您还应该通过一个高级示例流来说明用户如何与此系统交互和/或数据如何通过它。

用户故事是构建此框架的绝佳方式。请记住，您的系统可能包含具有不同用例的不同类型的用户。

推荐解决方案
有人称之为技术架构部分。再次，尝试通过用户故事来具体化这一点。可以包含许多子部分和图表。

先提供一张大图，然后填写大量细节，确保即使你出去度假了，团队中的另一位工程师也可以阅读它并按照你的描述实施解决方案。

替代方案
在提出上述解决方案时，您还考虑了什么？替代品的优点和缺点是什么？您是否考虑购买第三方解决方案 - 或使用开源解决方案 - 解决此问题而不是构建自己的问题？

监控和警报
我喜欢包括这一部分，因为人们经常事后才去考虑它们或者干脆忽略它们，当事情出了岔子，他们一筹莫展。

跨团队配合方面
是否会增加外呼和开发团队的负担？
它会花多少钱？
它是否会导致系统延迟？
它是否暴露了安全漏洞？
有什么负面后果和副作用？
支持团队如何与客户沟通？

讨论
任何你不确定的公开问题，你想让读者权衡的有争议的决定，建议未来的工作，等等。

详细的范围和时间表
本节主要是由参与该项目的工程师，他们的技术主管和他们的经理阅读。因此，本节在文档的最后。

从本质上讲，这是您计划执行项目每个部分的方式和时间的细分。有很多内容可以准确地确定范围，因此您可以阅读这篇文章以了解有关范围的更多信息。

我倾向于将设计文档的这一部分视为正在进行的项目任务跟踪器，因此每当我的范围估计发生变化时，我都会更新它。但这更多的是个人偏好。

怎么写?
下面让我们来谈谈写作风格。我保证这与你的高中英语课不同。

写得尽可能简单
不要试着写你读过的学术论文。它们是为了给期刊评论家留下深刻印象。您的文档是为了描述您的解决方案并从您的队友那里获得反馈而编写的。多运用类似这些：

· 简单的话

· 短句

· 项目符号列表和/或编号列表

· 具体的例子，如“用户爱丽丝连接她的银行账户，然后…”

添加大量表格和图示
表格通常可用于比较几个可能的选项，图表通常比文本更容易解读。我已经用Google Drawing创建图表了。

专业提示：请记住在屏幕截图下添加指向图表的可编辑版本的链接，以便以后在事情不可避免地发生变化时轻松更新。

包括数字
问题严重程度通常决定了解决方案。为了帮助审阅者了解实际状况，请包括实际数字，如数据库行数，用户错误数，延迟 - 以及这些数据如何随着使用情况而扩展（请记住您的Big-O表示法？）。

试着变得有趣
规范不是学术论文。此外，人们喜欢阅读有趣的东西，所以这是让读者保持参与的好方法。尽管如此，不要喧宾夺主。

进行测试
在将设计文档发送给其他人进行审核之前，请自己作为审核人员过一遍。您对此设计有什么疑问？然后先发制人地解决它们。

做假期测试
如果您现在无法访问互联网，那么您团队中的某个人是否可以阅读该文档并按照您的意图实施该文档？

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

处理
设计文档可帮助您在浪费大量时间实施错误解决方案或解决错误问题之前获得反馈。获得良好反馈有很多艺术，但这是以后的事。现在，让我们专门讨论如何编写设计文档并获取反馈。

首先，参与项目的每个人都应该参与设计过程。如果技术主管最终推动了很多决定，那也没关系，但是每个人都应该参与讨论并参与设计。因此，本文中的“你”是一个真正的复数“你”，包括项目中的所有人。

其次，设计过程并不意味着你盯着白板写些理论化的想法，随意制作潜在的解决方案原型。这与在编写设计文档之前开始为项目编写生产代码不同，不要那样做。但你绝对应该随意写一些一次性代码来验证想法。

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

1、请您团队中经验丰富的工程师或技术负责人成为您的评审员。理想情况下，这将是一个受到尊重和/或熟悉问题细节的人。

2、进入带白板的会议室。

3、向这位工程师描述你正在解决的问题（这是非常重要的一步，不要跳过它！）。

4、然后解释你想到的实现，并说服他们这是正确的构建。

在开始编写设计文档之前完成所有这些操作可以让您在投入更多时间并接受任何特定解决方案之前尽快获得反馈。通常情况下，即使实施保持不变，您的审核员也可以指出您需要覆盖的极端案例，指出任何潜在的混淆区域，并预测您以后可能遇到的困难。

然后，在您撰写了设计文档的粗略草稿之后，让相同的审阅者再次阅读它，并通过在设计文档的“标题和人物”部分中添加他们的名称作为审阅者来标记它。这为审阅者创造了额外的激励和责任。

在这方面，考虑为设计的特定方面添加专门的审阅者（例如SRE和安全工程师）。

一旦您和审核人员确定了，请随时将设计文档发送给您的团队，以获得额外的反馈和知识共享。我建议将反馈收集过程的时间限制在1周左右，以避免延误。致力于解决人们在该周内留下的所有问题和评论。

最后，如果您的审阅者和其他阅读该文档的工程师之间存在很多争议，我强烈建议您在文档的“讨论”部分中合并所有争议点。然后，与各方召开会议，当面谈论这些分歧。

每当讨论主题长度超过5条评论时，转向当面讨论往往效率更高。请记住，即使每个人都无法达成共识，您仍然有责任进行最后的沟通。

在最近与Shrey Banga谈论此事时，我了解到Quip有一个类似的过程，除了在您的团队中拥有经验丰富的工程师或技术负责人作为审阅者之外，他们还建议让不同团队的工程师审核该文档。我没有尝试过这个，但我当然可以看到这有助于从不同角度的人那里获得反馈，并提高文档的一般可读性。

完成上述所有操作后，即可开始实施！对于额外的布朗尼点，在实施设计时将此设计文档视为活文档。每次您更改原始解决方案或更新范围的内容时，请更新文档。这样你就不必向所有利益相关者反复解释事情，你会感谢我的。

最后，让我们真正了解一下：我们如何评估设计文档的成功？

我的同事Kent Rakip对此有一个很好的答案：如果完成正确的投资回报率，设计文档就会成功。这意味着成功的设计文档实际上可能导致这样的结果：

1、您花了5天时间编写设计文档，这迫使您通过技术架构的不同部分进行思考

2、您可以从审阅者那里获得反馈，即X是建议架构中最具风险的部分

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

4、3天后，你发现X要么不可能，要么比你原先想要的要困难得多

5、您决定停止处理此项目并优先处理其他工作

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