如何才能写出好的软件设计文档？

如何写出好的软件设计文档？

作为一名软件工程师，我花了很多时间阅读和编写设计文档。在审阅了数百份文档后，我发现优秀的设计文档与项目成功之间存在很强的相关性。

本文将介绍如何编写一份优秀的设计文档。

为什么要写设计文档？

设计文档是描述您计划如何解决问题的技术规范。已经有很多文章解释了为什么在开始编码之前应该编写设计文档，所以这里不再赘述，但我想补充一下：

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

设计文档的主要目的是迫使您仔细思考设计并收集其他人的反馈以更好地完成您的工作。人们常常认为设计文档的目的是让别人理解一个系统或者作为参考文档。这些是设计文档有益的副作用，但它们绝不是其基本目的。

从经验来看，如果你的项目需要一个人月或更长时间，那么你应该写一份设计文档。此外，一些较小的项目可能会受益于迷你设计文档。

但不同的工程团队，甚至同一团队的工程师，编写设计文档的方式存在很大差异。接下来我们来谈谈一个好的设计文档的内容、风格和流程应该是什么样的。

设计文件应该包含哪些内容？

设计文档描述了问题的解决方案。由于每个问题的性质不同，设计文档的结构也不同。

以下是您至少可以考虑将其包含在文档中的内容列表。

职称和成绩

设计文档标题、作者（应与计划参与该项目的人员列表相同）、审阅文档的人员（我们将在“流程”部分更详细地讨论这一点）以及文档的上次更新日期。

概括

摘要可以帮助公司中的任何工程师了解文档的内容并决定是否继续阅读文档的其余部分。摘要最多可以包含3个部分。

背景

描述正在解决什么问题，为什么这个项目是必要的，人们需要什么知识来评估这个项目，以及它与技术策略、产品策略或季度团队目标的关系。

目标和非目标

目标部分必须包含：

描述项目对用户的影响-您的用户可能是另一个工程团队或另一个系统。

指定如何使用指标来衡量项目成功-如果您可以链接到指标仪表板，那就更好了。

非目标同样重要，它描述了项目未解决的问题并使每个人都达成共识。

地标

您的产品经理和老板可以使用一系列可衡量的检查点来大致了解项目每个部分何时完成。如果项目时间超过1个月，我建议您将项目划分为面向用户的里程碑。

在指定里程碑时，您可以使用日历日期来考虑延迟、假期、会议等因素。例如：

开始日期：2018年6月7日

里程碑1–在黑暗模式下运行新系统MVP：2018年6月28日

里程碑2–旧系统退役：2018年7月4日

结束日期：向新系统添加新功能X、Y、Z：2018年7月14日

如果这些里程碑中的任何一个的预计到达时间发生变化，应在此处添加[更新]，以便相关人员可以轻松查看更新的内容。

目前计划

除了描述实际的实现之外，还应该提供示例来说明用户如何与系统交互以及数据如何流经系统。

此时可以使用用户故事。请记住，您的系统可能有不同类型的用户和不同的使用场景。

拟议计划

有人称这部分为技术架构。该部分还可以通过用户故事进行扩展，其中可以包含多个小节和图表。

从大局开始，然后填写细节。您希望确保即使您在荒岛上度假，团队中的其他工程师也可以实施您所描述的解决方案。

其他替代方案

在提出上述解决方案的同时，您是否也考虑过其他选择？替代方案的优点和缺点是什么？您是否考虑过使用第三方解决方案（或使用开源解决方案）来解决问题，而不是自己构建解决方案？

监控报警

人们常常把这部分视为事后诸葛亮，甚至忽视它。当问题出现时，他们很忙，但他们不知道该怎么办，也不知道为什么会出现这些问题。

跨团队影响力

这会增加监管机构和DevOps的负担吗？

它要多少钱？

会增加系统延迟吗？

它会暴露系统安全漏洞吗？

会造成什么负面后果和副作用？

支持团队应该如何与客户沟通？

讨论

这部分可以包括您不确定的问题、您希望阅读文档的人做出决定的有争议的决定、对未来工作的建议等。

详细范围和时间表

本节主要供参与项目的工程师、技术经理和经理阅读。因此，本节放在文档的末尾。

本质上，这是项目计划如何以及何时实施的详细说明，并且可以包含很多内容。

我倾向于将本部分视为项目任务跟踪器，因此每次范围估计发生变化时我都会更新它。但这更多的是个人喜好。

如何写出好的文档

既然我们已经讨论了一个好的设计文档应该包含什么，那么我们来谈谈写作风格。

尽可能简单

不要像以前读过的学术论文那样编写设计文档。论文是为了给期刊审稿人留下深刻印象，而编写设计文档是为了描述您的解决方案并获得其他人的反馈。您可以通过以下方式使文档更易于管理：

简单的话

使用短句

使用符号列表和编号列表

举出具体例子

添加图表

图表有助于比较多个选项，并且通常比文本更容易理解。我经常使用GoogleDrawing来创建图表。

请记住在屏幕截图下方添加指向图表源文件的链接，以便在发生更改时可以更新图表。

包含数字

问题的大小往往决定解决方案的大小。为了更好地帮助审阅者了解情况，请在文档中使用实际数字，例如数据库行数、用户错误数、延迟以及这些数字与使用情况的关系。（还记得大O符号吗？）

增添乐趣

请记住，技术规范不是学术论文。人们也喜欢阅读有趣的东西，但不要仅仅为了好玩而偏离核心思想。

自视

在将设计文档发送给其他人审阅之前，假装自己是审阅者。您对此设计文件有疑问吗？然后在提交文档之前解决这些问题。

假期测试

如果您独自一人并且无法访问互联网，团队中的其他人可以阅读此文档并按照您的预期实施吗？

设计文档的主要目的不是知识共享，但它是评估清晰度并允许其他人为您提供有用反馈的好方法。

对待

设计文档可以帮助您在浪费大量时间实施错误的解决方案或解决错误的问题之前获得反馈。获得良好反馈是一门艺术，但那是另一回事了。现在让我们讨论如何获得设计文档的反馈。

首先，参与项目的每个人都应该参与设计过程。虽然很多决定是由技术主管做出的，但这没关系，至少每个人都应该参与讨论并接收他们的设计。

其次，设计过程并不一定需要盯着白板并在上面画出不同的想法。您可以开始并制作不同可能解决方案的原型。这与在编写设计文档之前就开始编写代码不同。请随意输入一次性代码来测试您的想法。为了确保您的代码仅用作概念证明，任何原型代码都不能合并到master中。

了解如何使用您的项目后，请按照以下步骤操作：

请团队中经验丰富的工程师或技术经理审查您的文档。理想情况下，审阅者应该是受人尊敬并且已经熟悉问题边缘的人。

在带有白板的会议室中进行审核。

向审稿人描述您正在解决的问题（这是非常重要的一步，不要跳过它！）。

然后向审阅者解释您将如何实施您的想法并说服他们这是正确的解决方案。

在开始正式编写设计文档之前完成所有这些步骤可以让您在投入更多时间并最终确定解决方案之前尽快获得反馈。通常，即使实现可能保持不变，审阅者仍然会指出您需要涵盖的极端情况或潜在的歧义，并预测您以后可能遇到的困难。

当你写完设计文件的草稿后，让之前的审稿人再读一遍，并在设计文件的“标题和文字”部分写下他们的名字，作为对审稿人的鼓励，并表明他们是你负责的用于您自己的审核操作。

添加审阅者姓名时，请考虑针对特定问题添加不同的审阅者（例如SRE和安全工程师）。

完成审核后，将设计文档发送给您的团队以获取进一步反馈。我建议将此时间限制在1周左右，以避免延误。尝试在一周内解决他们留下的任何问题。

最后，如果您对阅读该文档的审阅者和其他工程师有不同意见，我强烈建议您将这些争议放在文档的讨论部分。然后与各方举行会议讨论这些分歧。

如果某个话题的评论数超过5条，面对面的讨论往往会更有效。请记住，即使您无法让每个人都同意，您仍然可以做出决定。

最近在与ShreyBanga谈论这个问题时，我了解到Quip有一个课程类似的流程，只不过除了让团队中经验丰富的工程师或者技术经理充当审阅者之外，他们还建议让不同团队的工程师来审阅设计文档。我没有尝试过这样做，但它确实有助于获得不同观点的人的反馈，这可以进一步提高文档的质量。

完成以上所有步骤后，就可以开始实施了！在设计实施时，设计文档可以被视为活动文档。当您对实施进行更改时，请更新文档，这样您就不必向所有利益相关者反复解释更改。

那么我们如何评价一份设计文档的成功呢？

我的同事KentRakip对这个问题的回答是：如果设计文档获得了正确的投资回报(ROI)，那么它就是成功的。也就是说，成功的设计文档可以带来：

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

您从审阅者那里获得反馈，并知道架构的某些部分具有更高的风险。

您决定首先解决这些问题以降低项目的风险。

3天后，你发现这些问题要么不可能，要么比你原来想象的要困难得多。

您决定停止该项目并从事其他工作。

在本文开头，我们说过设计文档的目的是为了确保工作正确完成。在上面的示例中，由于设计文档的原因，您只花了八天而不是几个月就决定终止该项目。在我看来，这似乎也是一个非常成功的结果。

英文原文

https://medium.freecodecamp.org/how-to-write-a-good-software-design-document-66fcf019569c