合辑|翟柯，赵云如果你是软件开发人员或架构师，你一定知道在开发行业有这样一种普遍存在的“文档纠缠症”：一边抱怨写文档浪费时间，一边抱怨别人不写文档。可以说，设计文档可以说是日常工作中非常重要但又容易被忽视的一部分。编写软件设计文档(SDD)的好处很多，其主要目的是迫使开发人员思考软件设计并收集他人的反馈以更好地完成工作。也是其他人了解系统的参考文档。好的文档和项目的成功之间有很强的相关性。相信网上有很多相关的文章和教程告诉大家如何写SDD，这里不再赘述。但很多人常常犯“教条主义”：虽然设计文档包含很多段落、图表和细节，但并没有产生多少价值，甚至连需要解决的问题都没有涵盖。在本文中，我们将讨论软件设计文档中最容易被忽视的几个问题，以免因为这些疏忽误导读者，甚至延误责任项目。什么时候需要设计文档每当有新的需求或者原有功能发生变化时，我们都需要先编写设计文档，然后再进行相关的开发。该设计文档需要所有项目利益相关者进行审查。设计文档是SDLC（软件开发生命周期）设计阶段的结果。设计文档的输入标准是需求明确的需求文档。一旦需求在收集阶段最终确定，设计阶段就开始了。写给谁很重要。这是设计文档中最被低估的部分，缺少它会给读者带来很多困惑。每个设计文档都应该有一个目的，其中提到了设计文档的目标受众。假设我们写一个高层设计文档（HLDD）来实现服务间通信。这份文档包含了我们需要在基础设施上做哪些改变，以及实现发布-订阅模型需要哪些技术栈。此HLDD针对基础架构和微服务相关团队的架构师。如果写作没有目的性，导致初级开发者阅读本文档，很可能无法理解SDD的所有内容，从而提出一堆不明确的问题，给作者回复造成负担。为避免这种情况，建议您提及文档的目标受众。识别未知数理想情况下，一旦需求和变更点明确，就开始编写SDD。但是对于更复杂的需求，总会有一些未知的因素。如果我们在编写SDD的时候能够发现这些未知数，了解具体情况，将有助于决策（评估工时等）。当我们知道这些未知因素后，我们就可以与相关人员讨论解决方案，然后修改我们的设计。这是非常有必要的。在平时的工作中，由于不可预见的不确定因素，造成许多无法挽回的损失。如果文档编写者只注重线下“抢”解决问题，而忽略了这些在文档中的考虑和记录，久而久之，SDD的作者要么换团队，要么换工作，导致这些未知因素，无人知晓，无人可追溯。如果这种现象发生在复杂的SDD中，那么它会给SDLC的实施阶段带来巨大的问题。需求分析在收集需求的阶段，大部分时间都花在分析需求上。在设计阶段，我们只需要跟进相关负责人讨论这些问题。但是，有时我们在写SDD的时候会发现新的需求，所以我们需要对这些需求进行添加、跟踪和整理。最好以表格的形式列出这些，比如下表：风险分析在写SDD的时候，可能会有一些不确定性。例如，我们需要在分布式环境中部署代码。由于与AWS（亚马逊云计算）业务团队的谈判已经进入收尾阶段，考虑到本项目将部署在AWS上级，需要体现在我们的设计文档中。由于交易尚未敲定且不可预测，该公司有可能暂时决定不使用AWS，而选择GCP（谷歌云计算）来部署代码。在这种情况下，我们的SDD中的内容需要修改。因此，与AWS的未决交易对我们来说是一种风险。在设计文件中提及风险，并说明影响范围，以便所有项目利益相关者都能意识到这些问题。DOD（DefinitionofDone）每个设计文档都有不同的写作目的，所以没有标准来衡量一个设计文档的DOD应该是多少。然而，一般来说，如果解决了以下几点，设计文档就被认为是完整的：SDD是在参考需求和分析文档之后创建的。所有读者都旨在能够理解SDD。SDD涵盖了本文前面提到的所有要点。通过设计文档，可以快速拆分任务。设计文件得到所有项目利益相关者的批准。结束语除了上面提到的几点，还有很多细节可以帮助我们写好SDD，比如文档的长度合适，图表数量合适等等，就不一一介绍了这里。当你掌握了这些要素，相信你一定能写出高价值的设计文档。原文链接：https://dzone.com/articles/ingredients-for-a-perfect-design-document?fromrel=true译者介绍翟柯，社区编辑，目前在杭州从事软件研发，并曾在电子商务、征信系统等方面工作，享受分享知识的过程，丰富你的生活。
