其它篇 -- 【如何写好软件设计文档】

<= 目录

前言

设计文档用于描述我们打算如何处理问题的方案。在编写设计文档的过程，我们需要对问题进行分析，并设计出解决方案。在设计评审时收集反馈，对方案进行完善，确保正确地完成项目。

文档结构

1. 标题和人员
   系统内容相关的标题。人员包括：项目参与者，文档审阅者，文档更新时间。
2. 摘要
   简要概括文档内容，以及文档的适用读者。目的是让读者决定是否需要详细阅读。
3. 背景
   描述为什么要做这个项目，需要解决什么问题。
4. 技术方案
   包括：1、用户与系统的交互；2、系统的数据流；
   技术方案应该足够的清晰和明确，尽量做到他人根据设计文档的描述即可实现解决方案。
5. 代替方案
   更提议方案对比，代替方案有哪些优缺点？
6. 时间计划

写作要求：

设计文档的编写要保证可读性，达到以下两个效果：

1. 确保评审人员能够清晰地了解整个系统，从而提出更有价值的反馈。
2. 开发人员可以根据文档准确地实现功能。

下面是具体的建议：

• 尽量用短词短句
• 使用逻辑图表(UML)
• 使用符号列表或编号列表
• 提供具体示例
• 包含数字
  问题的规模往往决定了解决方案的复杂度。具体的数据可以直观地让评审人员了解项目规模，例如：预期用户量、数据库关键表的预期数据量、对网络延迟或IO操作的预期超时时间
• 原型代码和概念验证
  编写设计文档过程中，可以通过编写原型代码来做概念验证，在扩展方案设计思路的同时，也提高了方案可行性。

tips：
使用到图表的，可给截图添加源文件连接，方便快速更新。

讨论

对于待确定或者存在争议的问题，可以提出来讨论。

文章总结

设计文档的目标是 确保做正确的事情。好的设计文档可以确保该项工作的**投入产出(ROI)**是合理的。比如下面这个例子：

1. 你花五天时间编写设计文档，分析问题并设计出方案
2. 在评审会上，得到反馈 X是方案中风险最高的
3. 你决定先实施X，降低项目风险
4. 三天后，你发现X可行性过低
5. 你决定暂缓这个项目，优先处理其他工作

整个流程下来，我们花了8天时间发现问题并确定暂缓项目。如果没有设计文档这一流程，可能得浪费更多时间成本才发现问题。