如何编写一个好的软件设计文档——Medium中文站
作为一名软件工程师，我花了很多时间阅读和编写设计文档。在完成了数百篇这些文档之后，我亲眼目睹了优秀设计文档与项目最终成功之间的强烈关联。
本文试图描述使设计文档变得更好的原因。
本文分为4个部分：
- 为什么要写一份设计文件
- 什么在设计文档，包括
- 怎么写
- 围绕它的过程
为什么要写一个设计文件？
设计文档 - 也称为技术规范 - 描述了您计划如何解决问题。
关于为什么在进入编码之前编写设计文档很重要的原因已经有很多文章。所以我在这里说的是：
设计文档是确保正确工作完成的最有用工具。
设计文档的主要目标是通过强迫您思考设计并收集其他人的反馈来提高您的效率。人们通常认为设计文档的目的是教会其他人关于某个系统或稍后作为文档。虽然这些可能是有益的副作用，但它们本身并不是目标。
作为一般的经验法则，如果您正在处理可能需要1个工程师月或更长时间的项目，那么您应该编写设计文档。但不要止步于此 - 许多小型项目也可以从迷你设计文档中受益。
大！如果您还在阅读，您会相信设计文档的重要性。但是，不同的工程团队，甚至同一团队的工程师，经常以不同的方式编写设计文档。让我们来谈谈优秀设计文档的内容，风格和流程。
照片来自Todd Quackenbush的 Unsplash
在设计文档中包含哪些内容？
设计文档描述了问题的解决方案。由于每个问题的性质不同，您自然希望以不同的方式构建您的设计文档。
首先，以下是您应该至少考虑 在下一个设计文档中包含的部分列表：
标题和人物
您的设计文档的标题， 作者（应该与计划参与此项目的人员列表相同），文档的审阅者（我们将在“处理”部分中详细讨论）下面），以及本文档最后更新的日期。
概观
高级摘要，公司的每位工程师都应该理解并使用它来决定是否有必要阅读其余的文档。最多应为3段。
上下文
对手头问题的描述，为什么这个项目是必要的，人们需要知道什么来评估这个项目，以及它如何适应技术战略，产品战略或团队的季度目标。
目标和非目标
目标部分应：
- 描述项目的用户驱动影响 - 您的用户可能是另一个工程团队甚至是另一个技术系统
- 指定如何使用指标衡量成功 - 如果您可以链接到跟踪这些指标的仪表板，则可以获得奖励积分
非目标对于描述您不会修复哪些问题同样重要，因此每个人都在同一页面上。
里程碑
一个可衡量的检查点列表，因此您的PM和您的经理的经理可以浏览它并大致了解项目的不同部分何时完成。如果项目超过1个月，我建议您将项目分解为面向用户的主要里程碑。
使用日历日期，以便考虑无关的延迟，假期，会议等。它应该看起来像这样：
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
[Update]如果其中一些里程碑的ETA发生变化，请在此处添加一个小节，以便利益相关者可以轻松查看最新的估算值。
现有解决方案
除了描述当前的实现之外，您还应该通过一个高级示例流来说明用户如何与此系统交互和/或数据如何通过它。
一个用户故事是这个框架的好方法。请记住，您的系统可能包含具有不同用例的不同类型的用户。
提出的解决方案
有些人称之为技术架构部分。再次，尝试通过用户故事来具体化这一点。随意包含许多子部分和图表。
首先提供一个大的图片，然后填写大量 的 细节。瞄准一个你可以写这个的世界，然后在一个荒岛上度假，团队中的另一位工程师可以阅读它并按照你的描述实施解决方案。
替代方案
在提出上述解决方案时，您还考虑了什么？替代品的优点和缺点是什么？您是否考虑购买第三方解决方案 - 或使用开源解决方案 - 解决此问题而不是构建自己的问题？
可测试性，监控和警报
我喜欢包括这一部分，因为人们经常把它视为事后的想法或者一起跳过它们，而且当事情破裂并且他们不知道如何或为什么时，它几乎总会回来咬它们。
跨团队影响力
如何增加电话和开发负担？
它需要多少钱？
它是否会导致系统出现任何延迟回归？
它是否暴露了任何安全漏洞？
有什么负面后果和副作用？
支持团队如何与客户沟通？
打开问题
任何你不确定的未解决的问题，你想让读者权衡的有争议的决定，建议未来的工作，等等。这部分的一个诙谐的名字是“已知的未知数”。
详细的范围和时间表
本节主要是由参与该项目的工程师，他们的技术主管和他们的经理阅读。因此，本节在文档的最后。
从本质上讲，这是您计划执行项目的每个部分的方式和时间的细分。有很多内容可以准确地确定范围，因此您可以阅读此文章以了解有关范围界定的更多信息。
我倾向于将设计文档的这一部分视为正在进行的项目任务跟踪器，因此每当我的范围估计发生变化时，我都会对此进行更新。但这更多的是个人偏好。
在Unsplash上 由rawpixel 拍摄
怎么写
现在，我们已经谈了什么进入一个好的设计文档，让我们来谈谈写作风格。我保证这与你的高中英语课不同。
写得尽可能简单
不要试着像你读过的学术论文那样写作。它们是为了给期刊评论家留下深刻印象。您的文档是为了描述您的解决方案并从您的队友那里获得反馈而编写的。您可以通过以下方式实现清晰：
- 简单的话
- 短句
- 项目符号列表和/或编号列表
- 具体的例子，如“用户爱丽丝连接她的银行帐户，然后......”
添加大量图表和图表
图表通常可用于比较几个可能的选项，图表通常比文本更容易解析。我已经用Google Drawing创建图表了。
专业提示：请记住在屏幕截图下添加指向图表的可编辑版本的链接，以便您可以在以后不可避免地发生变化时轻松更新。
包括 数字
问题的规模通常决定了解决方案。为了帮助审阅者了解世界状况，请包括实际数字，例如数据库行数，用户错误数，延迟数以及这些数据如何随着使用情况而扩展。还记得你的Big-O符号吗？
试着变得有趣
规范不是学术论文。此外，人们喜欢阅读有趣的东西，所以这是让读者保持参与的好方法。尽管如此，不要过分夸大核心思想。
如果你和我一样，很难搞笑，Joel Spolsky（显然以他的喜剧天赋而闻名......）有这样的提示：
有趣的最简单的方法之一就是在没有被 要求时 具体说明 [......例子：]而不是说“特殊利益”，而是说“左撇子avacado农民”。
进行怀疑测试
在将您的设计文档发送给其他人进行审核之前，请假装成为审核人员。您对此设计有什么疑问和疑问？然后先发制人地解决它们。
做假期测试
如果您现在无法访问互联网，那么您团队中的某个人是否可以阅读该文档并按照您的意图实施该文档？
设计文档的主要目标不是知识共享，但这是一种评估清晰度的好方法，以便其他人可以实际为您提供有用的反馈。
照片由SpaceX公司对 Unsplash
处理
啊，是可怕的P字。设计文档可帮助您在浪费大量时间实施错误解决方案或解决错误问题之前获得反馈。获得良好反馈有很多艺术，但这是后来的文章。现在，让我们专门讨论如何编写设计文档并获取反馈。
首先，参与项目的每个人都应该参与设计过程。如果技术主管最终决定做出很多决定，那也没关系，但是每个人都应该参与讨论并购买设计。因此，本文中的“你”是一个真正的复数“你”，其中包括项目中的所有人。
其次，设计过程并不意味着你盯着白板理论化的想法。随意将您的手弄脏并制作潜在的解决方案原型。这与在编写设计文档之前开始为项目编写生产代码不同。不要那样做。但你绝对应该随意写一些hacky一次性代码来验证一个想法。为了确保您只编写探索性代码，请将此原型代码中的任何一个都合并为master。
之后，当您开始了解如何进行项目时，请执行以下操作：
- 请您团队中经验丰富的工程师或技术负责人成为您的评审员。理想情况下，这将是一个受到良好尊重和/或熟悉问题边缘情况的人。如有必要，用boba贿赂他们。
- 进入带白板的会议室。
- 描述你正在向这位工程师解决的问题（这是非常重要的一步，不要跳过它！）。
- 然后解释你想到的实现，并说服他们这是正确的构建。
在开始编写设计文档之前完成所有这些操作可以让您在投入更多时间并接受任何特定解决方案之前尽快获得反馈。通常情况下，即使实施保持不变，您的审核人员也可以指出您需要覆盖的极端案例，指出任何可能的混淆区域，并预测您以后可能遇到的困难。
然后，在您撰写了设计文档的粗略草稿后，让相同的审阅者再次阅读，并通过在设计文档的“ 标题和人物”部分中添加他们的名称作为审阅者来标记它。这为审阅者创造了额外的激励和责任。
在这方面，考虑为设计的特定方面添加专门的审阅者（例如SRE和安全工程师）。
一旦您和审核人员签字，请随时将设计文档发送给您的团队，以获得更多反馈和知识共享。我建议将反馈收集过程限时约1周，以避免延误。致力于解决人们在该周内留下的所有问题和评论。留下评论悬挂=坏业力。
最后，如果您，您的审阅者和其他阅读该文档的工程师之间存在很多争议，我强烈建议您在文档的“ 讨论”部分中合并所有争用点。然后，与各方召开会议，亲自谈论这些分歧。
每当讨论主题长度超过5条评论时，转向亲自讨论往往会更有效率。请记住，即使每个人都无法达成共识，您仍然有责任进行最后的通话。
在最近与Shrey Banga谈论此事时，我了解到Quip有一个类似的过程，除了作为审阅者在您的团队中拥有经验丰富的工程师或技术负责人之外，他们还建议让不同团队的工程师审核该文档。我没有试过这个，但我当然可以看到这有助于从不同角度的人那里获得反馈，并提高文档的一般可读性。
完成上述所有操作后，即可开始实施！对于额外的布朗尼点，在实施设计时将此设计文档视为活文档。每当您了解到导致您更改原始解决方案或更新范围的内容时，请更新文档。如果您不必一遍又一遍地向所有利益相关者解释，您会感谢我。
最后，让我们真正了解一下：我们如何评估设计文档的成功？
我的同事Kent Rakip对此有一个很好的答案：如果完成正确的投资回报率，设计文档就会成功。这意味着成功的设计文档实际上可能导致这样的结果：
- 您花了5天时间编写设计文档，这迫使您通过技术架构的不同部分进行思考
- 您可以从审阅者那里获得反馈，这
X是建议架构中最具风险的部分 - 您决定先实施
X以降低项目风险 - 3天后，你发现这
X是不可能的，或者比你原先预期的要困难得多 - 您决定停止处理此项目并优先考虑其他工作
在本文开头，我们说设计文档的目标是确保正确的工作完成。在上面的示例中，由于这个设计文档，您可能只花了8天时间，而不是浪费可能几个月才能中止此项目。对我来说似乎是一个非常成功的结果。
如果您有任何问题或反馈，请在下面留言！我也很想知道你如何在团队中以不同的方式设计文档。