软件设计文档最容易忽略内容看这里！

Posted 2022-06-09 WOT技术大会

如果你是软件开发人员或架构师，一定知道开发行业里普遍存在这样一种“文档纠结症”：一面抱怨写文档浪费时间，一面抱怨别人不写文档。可以说，设计文档可以说是日常工作中非常重要但又容易被忽略的部分。

编写软件设计文档（SDD）的好处很多，其主要目的是使开发者对软件设计进行强制性思考, 并收集他人的反馈, 以便更好地完成工作。同时也是让其他人了解系统的参考文档。好的文档与项目成功之间有很强的关联性。

相信很多网上有很多相关的文章、教程来告诉你如何写SDD，这里不再赘述。但很多人往往犯了“教条”主义：设计文档虽然包含大量段落、图表和细节，但却并没有产生多大价值，甚至连所需要解决的问题都没有覆盖到。

在本文中，我们将讨论软件设计文档中最容易忽略的几个问题，避免因这些疏忽而误导了读者，甚至延误了所负责的项目。

PART 01

什么时候才需要设计文档？

每当有新的需求或者原有功能变更的时候，我们就需要先编写设计文档，然后在进行相关开发。该设计文档需要由所有项目干系人进行审查。

设计文档是 SDLC （软件开发生命周期）设计阶段的结果。设计文档的输入标准就是一份需求明确的需求文档。一旦需求在收集阶段最终确定，那么设计阶段就要开始了。

PART 02

写给谁看很重要

这是设计文档中最被低估的部分，没有这部分会给读者带来很多困惑。每个设计文档都应该有一个编写目的，其中提到该设计文档的目标读者对象。

假设我们编写了一个高级设计文档 (HLDD) 来实现服务间通信。该文档包含了我们需要在基础架构哪些方面进行更改，以及实现发布-订阅模型需要哪些技术栈等。此 HLDD 面向于基础架构和微服务相关团队的架构师。

如果没有编写目的，导致初级开发人员阅读了该文档，他们很可能无法理解 SDD 的所有内容，以至于问一堆不明确的问题，这样就造成了作者回复的负担。

为避免出现这种情况，建议你提及文档的面向读者群体。

PART 03

识别未知因素

在理想情况下，一旦需求和变更点明确，就会开始编写SDD。但是对于比较复杂的需求来说，总是会有一些未知因素。

如果我们在编写SDD时能够发现这些未知因素，并且了解具体内容，那么将有助于作出决策（评估工时等）。当我们知道了这些未知因素后就可以与相关人员探讨解决方法，然后去修改我们的设计方案。

这十分必要。平时工作中不乏因为没有预测不确定因素而造成难以挽回的损失。如果文档写作者只注意在线下“冲锋”解决问题，而忽略了在文档中考虑并记录这些，随着时间的推移，SDD的作者要么换了团队，要么跳槽了，导致这些未知因素没有人知道，导致没有人能去追踪。如果这种现象发生在复杂的 SDD 中，那么它会在 SDLC 的实现阶段产生巨大的问题。

PART 04

需求分析 

在收集需求阶段，大部分的时间都在分析需求。到设计阶段，我们只需要跟进相关负责人来探讨这些问题。然而有时我们在编写 SDD 时会发现新的需求，所以还需要添加、跟踪并且梳理这些需求。最好使用表格的形式来列举这些，如下面的表格：

PART 05

风险分析 

在写SDD的时候，可能会有一些不确定的点。例如，我们需要在分布式环境中部署代码，由于与AWS（亚马逊云计算）商务团队的洽谈已进入到了最后阶段，那么在我们的设计文档中就需要体现，考虑到这个项目将被部署在AWS上。

由于交易尚未敲定，不可预见，所以有可能公司临时决定不使用AWS而选择GCP（谷歌云计算）来部署代码。在这种情况下，我们的SDD中的内容就需要修改。因此，与AWS的未完成交易对我们而言是一个风险。

在设计文档中提及风险，并且阐述影响范围，这样就会让所有项目干系人有意识的关注这些问题。

PART 06

DOD（完成的定义）

每个设计文档都有不同的编写目的，因此无法以一个标准去衡量设计文档的 DOD 应该是什么。但是，一般来说，如果解决了以下几点，则认为设计文档已完成：

• SDD是参考需求和分析文档后创建的。
• 面向的所有读者都能够理解SDD。
• SDD 涵盖了本文前面提到的所有要点。
• 通过设计文档，可以快速的拆分任务。
• 设计文档得到了所有项目干系人的批准。

PART 07

结论    

除了上面所说的几点，还有很多其他细节可以帮助我们写好SDD，例如文档的长度多少为宜、图表的数量多少合适等，这里就不一一做介绍了。当你掌握了这些要素后，相信一定可以写出高价值含量的设计文档。