优秀的设计文档写法指南软件需求设计文档怎么写( 二 ) _文档

系统语境图示例
APIs 如果正在设计的系统暴露一个 API，那么勾勒出这个 API 通常是个好主意。然而，在大多数情况下，人们应该按捺住将正式接口或数据定义复制粘贴到文档中的诱惑，因为这些定义通常都很冗长，包含一些不必要的细节，而且很快就会过时。相反，人们应该聚焦于与设计及其权衡相关的部分。
数据存储存储数据的系统应该讨论如何及用何种大致的形式存储数据。和关于 API 的建议类似，并且理由相同，应该避免复制粘贴完整的模式定义。相反，要聚焦于与设计及其权衡相关的部分。
代码与伪代码除了一些描述新奇算法的场景，设计文档应该很少包含代码或伪代码。在适当的情况下，可以链接到设计实现的原型。
约束度影响软件设计和设计文档形状的主要因素之一就是方案空间的约束度。
极端的一个例子就是“绿地软件项目”，我们都知道目标，而且解决方案可以是任何最有意义的方案。这样一个文档可能涉及面很广，但它还需要快速定义一组规则，来允许对一组可控的解决方案进行细致研究。
另一方面，系统中可能的方案都定义得很好，但是完全不清楚如何将它们组合起来实现目标。这可能是一个很难更改的遗留系统，而且它不是按照你希望的样子设计的，或者是一个程序库设计，需要在宿主编程语言的约束下运行。
【优秀的设计文档写法指南软件需求设计文档怎么写】在这种情况下，你也许能列举出相对容易做的事情，但你需要费些心思将这些事情组合起来，从而实现目标。可能有很多方案，但没有一个是非常好的，因此，这样一个文档应该聚焦于根据所有确定的权衡点来选择最佳方案。
可供考虑的备选方案本节列出了能合理实现类似结果的备选设计。重点应该放在每个设计所做的权衡，以及这些权衡如何导致选择这个设计的决定，而这正是这个文档的首要主题。
虽然简略介绍最终没有被选中的方案也没有什么，但是本节会非常明确地展示为什么被选中的方案是针对项目目标的最佳方案，以及读者可能想知道的，为什么其它方案提供的权衡针对目标方案是不太理想的。
交叉关注点在这里，你的组织可以确保像安全性、隐私性、可观测性等跨领域问题被纳入考虑范围。这些通常都是相对短的部分，解释了设计如何影响这些关注点以及如何解决这些关注点。团队应该将这些关注点标准化。
由于它们的重要性，谷歌项目需要有一个专门的隐私设计文档，并且有专门的隐私和安全审查。虽然这些审查只需要在项目启动时完成，但最好尽早与隐私和安全团队接触，以确保设计从一开始就将这些考虑在内。对于这些主题的专用文档，中心设计文档当然可以只引用它们，而不是详细介绍。

优秀的设计文档写法指南 软件需求设计文档怎么写( 二 )

猜你喜欢

优秀的设计文档写法指南软件需求设计文档怎么写( 二 )