如何编写好的软件设计文档

文章目录

• • **为什么要写设计文档**
  • **设计文档中应该包含哪些内容**
  • **标题和人员**
  • 概述
  • 背景
  • **目标和非目标**
  • **里程碑**
  • 现状
  • **建议方案**
  • **替代方案**
  • **可测试性、监控和 警**
  • 跨团队的影响力
  • 开放性问题
  • 详细的范围和时间表
  • 如何编写
  • 尽可能简单
  • 尽可能使用图和图表
  • 包含数字
  • 试着有趣一些
  • 做一轮自评
  • 做一轮休假测试
  • 流程

已剪辑自: https://zhuanlan.zhihu.com/p/59533572

作为一名软件工程师，我花了很多时间阅读和编写设计文档。在研究了数百篇这样的文档之后，我发现好的文档与项目成功之间有很强的关联性。

• 为什么要写设计文档
• 设计文档中应该包含哪些内容
• 如何编写
• 流程

为什么要写设计文档

设计文档 – 也被称作技术规范 – 描述了你计划如何去解决一个问题。已经有很多文章解释了编码之前编写设计文档的重要性。所以我在这儿要说的是:

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

人们一般会认为设计文档是用来告诉别人系统是怎么工作的或者作为档案留存。设计文档确实可以起到这些作用，但这些并不是最主要目标。设计文档的最主要目标是推动你去思考，去收集反馈。

作为一般性原则，如果你工作的项目需要1个人月或者以上，就需要写设计文档。但其实对于更小型的项目，编写设计文档也是有益的。

我想如果您还在阅读，那么你一定是认可设计文档的重要性。但是不同的工程团队，甚至同一团队的工程师，经常以不同的方式编写设计文档。让我们来谈谈好的设计文档的内容，风格和流程。

如何编写

既然谈到了好的设计文档的内容，那我们就聊聊写作风格。我保证这个和你高中的英语课可不一样。

尽可能简单

• 简单的单词
• 简短的句子
• 各种列表
• 具体的例子，如『用户李磊链接到自己的银行账户，然后…』

尽可能使用图和图表

图比文字更容易阅读，图表往往用来比较几个可能的选项。我用Google Drawing来制作图表。

包含数字

问题的规模往往会决定最终的方案。为了帮助评审人员了解整个问题的概况，列举出具体的数字，如数据库的行数，用户错误的数量以及这些数字如何随着使用情况扩展。还记得Big-O符 么p>

试着有趣一些

设计文档不是学术论文。人们喜欢阅读有趣的东西，所以这是让读者更投入的一个好办法。但不要为了显得有趣而偏离了文档的主题。如果你和我一样，不是一个很有趣的人，Joel Spolsky给过这样的建议 — 最简单的显得有趣的方法是在进行一般性描述的地方，使用非常具体的例子。与其说『特殊利益群体』，不如说『左撇子的牛油果民』

做一轮自评

在把文档发给其他人评审之前，自己先评审一遍。你对这样的设计有什么问题和疑惑有，就尽量先解决。

做一轮休假测试

加入你要休一个长假，并且没有 络，有没有团队的其他人根据这个文档可以按你的想法实现出来前面说的，设计文档的主要目标不是分享知识，而是一种有效的方式来激发别人给你有用的反馈。

流程

又是讨厌的流程！设计文档可以帮你在浪费大量时间去实现一个错误的方案或者尝试去解决一个错误的问题之前获得反馈。获得好的反馈可以有很多方法，后面会写文章介绍。现在，让我们讨论下如何编写设计文档并获得反馈。

首先，参与项目的所有人都应该参与设计的过程。虽然技术主管会做出很多决定，但每个人都应该参加讨论并认同最终的决策。所以这篇文章里提到的”你”或者”你们”都是指参与项目的所有人。

其次，设计的过程不是说盯着白板天马行空的去畅想。往往需要你着手去做一些可能的原型方案。这不意味着你要在编写设计文档之前就去写生产级别的代码。不要那样做。但你必须要写一些代码去验证你的想法。为了确保你只是写一些实验性质的代码，制定一个如『原型代码永远不能被合并到主代码分支』这样的规则。

在您开始了解如何进行项目之后，你需要执行以下几个操作

1. 请你团队中经验丰富的工程师或者技术主管作为评审人。理想情况下这个人应该对要解决的问题域非常熟悉。可以买杯咖啡贿赂下:)
2. 在会议室放个白板
3. 把你要处理的问题跟这位工程师描述下。（这一步很重要，千万不要跳过）
4. 然后把你设想的实现方式解释给这位工程师，并说服他（们）。这是非常值得去做的一件事情。

这些工作甚至可以在你编写设计文档之前就做，在投入更多时间以及纠结于某个具体细节前，尽早的获得反馈。通常即便实现方法是一样的，你的评审人也可以指出你没想到的边界情况，澄清一些容易混淆的问题，以及指出你未来可能遇到的一些困难。

在你完成设计文档初稿之后，让最初的评审人再审阅一遍。在文档的标题和人员部分写上评审人的名字。这也是对评审人员的一种认可和激励。

提醒一下，对于某些设计文档考虑邀请特定的专业评审人，如SRE工程师和安全工程师

你和评审人的工作结束之后，就可以把设计文档发送给你的团队以获得更多的反馈以及知识共享。我建议收集反馈的时间限定在1周以避免拖延。承诺在问题和评论提出的当周给予回复。如果不能及时给予反馈会造成很糟糕的后果。

最后，如果你，评审人和其他的工程师对于文档存在很多争议，我强烈建议把所有的争论点放在文档的”讨论”部分。然后召开会议和各方讨论这些分歧。

如果某个讨论的主题有超过5条评论，那么改成面对面的讨论会更有效率。记住即使最终无法达成共识，你仍有责任做出最后的决定。

最近在和Shrey Banga谈到这个时，我了解到Quip有类似的流程，除了找一个有经验的工程师或者技术主管作为评审人外，他们还建议邀请一个其他团队的工程师审阅这个文档。我虽然没有尝试过，但从不同角度收集反馈明显是有益的，同时也能改进文档的可读性。

完成上面所有这一切以后，就可以撸起袖子干活了。额外一点，要记得保持文档的更新。无论是工作范围或者方案的修改，都同步更新这个文档。这样你就不用一遍遍去跟别人解释这些问题。

最后让我们了解下如何评估一份文档是否成功p>

我的同事Kent Rakip 对此有一个很好的答案：如果该项工作的投入产出比（ROI）是合适的，那么设计文档就是成功的。这意味着成功的设计文档实际上会导致这样的结果：

1. 您花了5天时间编写设计文档，这迫使你从不同的方面考虑技术架构
2. 你从评审人员那里得到一些反馈，如X是建议的架构中风险最高的部分
3. 你决定首先实施X，降低项目风险
4. 3天后你发现X要么是不可行的，要么比原先设想的困难的多
5. 你决定停止这个项目，优先处理其他工作

在文章的开头，我们说过设计文档的目标是确保做正确的事情。在上面的例子中，由于有了设计文档，你只花了8天时间，而不是浪费几个月时间才去中止这个项目。这对我来说是非常好的一个结果。