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

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

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

本文分为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表示法？）。

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

进行测试
在将设计文档发送给其余人进行审核以前，请本身做为审核人员过一遍。您对此设计有什么疑问？而后先发制人地解决它们。

作假期测试
若是您如今没法访问互联网，那么您团队中的某我的是否能够阅读该文档并按照您的意图实施该文档？

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

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

首先，参与项目的每一个人都应该参与设计过程。若是技术主管最终推进了不少决定，那也不要紧，可是每一个人都应该参与讨论并参与设计。所以，本文中的“你”是一个真正的复数“你”，包括项目中的全部人。

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

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

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

进入带白板的会议室。

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

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

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

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

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

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

最后，若是您，您的审阅者和其余阅读该文档的工程师之间存在不少争议，我强烈建议您在文档的“讨论”部分中合并全部争议点。而后，与各方召开会议，当面谈论这些分歧。

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

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

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

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

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

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

您能够从审阅者那里得到反馈，即X是建议架构中最具风险的部分

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

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

您决定中止处理此项目并优先处理其余工做

在本文开头，咱们说设计文档的目标是确保正确的工做完成。 在上面的示例中，因为这个设计文档，您可能只花了8天时间而不是浪费几个月才能停止此项目。 对我来讲彷佛是一个很是成功的结果。

若是您喜欢这篇文章，请在Twitter上关注我，了解有关工程，流程和后端系统的更多帖子。

原文地址

文章来源： 网易云社区