1、为什么要写设计文档？设计文档也就是技术规范，用于描述你打算如何解决问题。已经有很多文章说明了为什么在开始编码之前要先写设计文档，这里不再赘述，不过我想再补充一句：设计文档是确保正确完成工作最有用的工具。设计文档的主要目的是迫使你对设计展开缜密的思考，并收集他人的反馈，以便更好地完成你的工作。人们通常认为，设计文档的目的是让其他人了解某个系统，或者作为参考文档。这些只是设计文档带来的有益的副作用，但绝不是它们的根本目的。
3、下面列出了一个清单，你至少可以考虑在文档中包含这些内容。标题和人物设计文档的标题、作者（应该与计划参与项目的人员名单相同）、文档的评审人员（我们将在“流程”部分详细讨论），以及文档的最后更新日期。
4、摘要摘要可以帮助公司的每位工程师理解文档的内容，并决定是否需要继续阅读文档的剩余部分。摘要最多可以包含 3 段内容。
6、目标和非目标目标部分应该包括：描述项目对用户的影响——你的用户可能是另一个工程团队或另一个系统。指定如何使用指标来度量项目的成功——如果可以链接到指标仪表盘那就更好了。非目标也同样重要，用于描述项目不会解决哪些问题，让每个人都达成共识。
7、里程碑一系列可衡量的检查点，你的 PM 和上司可以借助它们大致了解项目的每个部分将在什么时间完成。如果项目时间超过 1 个月，我建议你将项目分解为面向用户的里程碑。在设定里程碑时可以使用日历日期，把延期、假期、会议等因素都考虑进去。例如：开始日期：2018 年 6 月 7 日里程碑 1——以暗模式运行新系统 MVP：2018 年 6 月 28 日里程碑 2——弃用旧系统：2018 年 7 月 4 日结束日期：在新系统中添加新特性 X、Y、Z：2018 年 7 月 14 日如果其中一些里程碑的 ETA 发生变化，需要在此处添加 [更新]，相关人员可以很容易看到更新的内容。
10、其他替代方案在提出上述解决方案的同时，你还考虑了其他的方案了吗？替代方案的优点和缺点是什么？你是否考虑使用第三方解决方案——或使用开源解决方案——来解决问题，而不是自己构建解决方案？
11、监控和警报人们经常把这部分视为马后炮，甚至直接忽略掉。而在发生问题后，他们就手忙脚乱，却不知道该怎么办，也不知道为什么会发生这些问题。
14、详细的范围和时间表这一部分的主要阅读对象是参与该项目的工程师、技术主管和经理。因此，这部分放在文档的最后。从本质上讲，这是项目计划的实施方式和时间细分，可以包含很多内容。我倾向于将这一部分视为项目任务跟踪器，因此每当范围估计发生变化时，我都会更新它。但这更像是个人偏好。怎样才能写好文档在讲完优秀的设计文档应该包含哪些内容之后，现在让我们来谈谈写作风格。
15、尽可能保持简单不要把设计文档写成你曾经读过的学术论文。论文是为了给期刊评论家留下深刻印象，而编写设计文档是为了描述你的解决方案，并从其他人那里获得反馈。你可以通过以下方式让文档变得更清晰：用词简单使用短句使用符号列表和编号列表提供具体的示例
18、加入趣味性记住，技术规范不是学术论文。另外，人们喜欢阅读有趣的东西，但也不要为了趣味性而偏离了核心思想。
19、自审在将设计文档发给其他人评审之前，自己先假装是评审人员。你对这份设计文档有什么疑问？然后在发出文档之前把这些问题解决掉。
22、在你了解了如何进行项目之后，请执行以下步骤：请你团队中经验丰富的工程师或技术负责人来评审你的文档。理想情况下，评审人员应该是一个受到尊重并且对问题边缘情况已经很熟悉的人。在有白板的会议室里进行评审。向评审人员描述你正在解决的问题（这是非常重要的一步，不要跳过它！）。然后向评审人员解释你想要怎样实现你的想法，并说服他们这是正确的解决方案。
23、在开始正式编写设计文档之前完成所有这些步骤，可以让你在投入更多时间并敲定解决方案之前尽快获得反馈。通常情况下，即使实现方式可以保持不变，评审人员仍然会指出一些需要你覆盖到的极端情况，或者指潜在的不明确的地方，并预测你以后可能会遇到的困难。然后，在你为设计文档写了粗稿之后，让之前的评审人员再次阅读它，并在设计文档的“标题和人物”部分写下他们的名字，作为对评审人员的鼓励，也表示他们是有责任对自己的评审行为负责的。在添加评审人员名字时，可以考虑为特定的问题添加不同的评审人员（例如 SRE 和安全工程师）。
26、那么，我们如何评估一份设计文档成功与否？我的同事 Kent Rakip 对这个问题的回答是：如果能够获得正确的投资回报率（ROI），那么设计文档就是成功的。也就是说，一份成功的设计文档可能会导致：
27、你花了 5 天时间编写设计文档，迫使你对技术架构的不同部分进行了充分的思考。你从评审人员那里获得反馈，知道架构中某些部分具有较高的风险。你决定先解决这些问题，以便降低项目的风险。3 天后，你发现这些问题要么不可能发生，要么比你原先想象的要困难得多。你决定停止这个项目去做其他工作。
