一面抱怨写文档浪费时间,一面抱怨别人不写文档。可以说,设计文档可以说是日常工作中非常重要但又容易被忽略的部分。

编译 | 翟珂、云昭

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

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

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

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

什么时候才需要设计文档

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


图片


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

写给谁看很重要

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

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

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

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

识别未知因素

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

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

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

需求分析 

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

图片

风险分析 

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

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

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

DOD(完成的定义)

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

  • SDD是参考需求和分析文档后创建的。

  • 面向的所有读者都能够理解SDD。

  • SDD 涵盖了本文前面提到的所有要点。

  • 通过设计文档,可以快速的拆分任务。

  • 设计文档得到了所有项目干系人的批准。

结论

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

原文链接:

https://dzone.com/articles/ingredients-for-a-perfect-design-document?fromrel=true

译者介绍

翟珂,51CTO社区编辑,目前在杭州从事软件研发工作,做过电商、征信等方面的系统,享受分享知识的过程,充实自己的生活。