前言
设计文档用于描述我们打算如何处理问题的方案。在编写设计文档的过程,我们需要对问题进行分析,并设计出解决方案。在设计评审时收集反馈,对方案进行完善,确保正确地完成项目。
文档结构
- 标题和人员
系统内容相关的标题。人员包括:项目参与者,文档审阅者,文档更新时间。 - 摘要
简要概括文档内容,以及文档的适用读者。目的是让读者决定是否需要详细阅读。 - 背景
描述为什么要做这个项目,需要解决什么问题。 - 技术方案
包括:1、用户与系统的交互;2、系统的数据流;
技术方案应该足够的清晰和明确,尽量做到他人根据设计文档的描述即可实现解决方案。 - 代替方案
更提议方案对比,代替方案有哪些优缺点? - 时间计划
写作要求:
设计文档的编写要保证可读性,达到以下两个效果:
- 确保评审人员能够清晰地了解整个系统,从而提出更有价值的反馈。
- 开发人员可以根据文档准确地实现功能。
下面是具体的建议:
- 尽量用短词短句
- 使用逻辑图表(UML)
- 使用符号列表或编号列表
- 提供具体示例
- 包含数字
问题的规模往往决定了解决方案的复杂度。具体的数据可以直观地让评审人员了解项目规模,例如:预期用户量、数据库关键表的预期数据量、对网络延迟或IO操作的预期超时时间 - 原型代码和概念验证
编写设计文档过程中,可以通过编写原型代码来做概念验证,在扩展方案设计思路的同时,也提高了方案可行性。
tips:
使用到图表的,可给截图添加源文件连接,方便快速更新。
讨论
对于待确定或者存在争议的问题,可以提出来讨论。
文章总结
设计文档的目标是 确保做正确的事情。好的设计文档可以确保该项工作的**投入产出(ROI)**是合理的。比如下面这个例子:
- 你花五天时间编写设计文档,分析问题并设计出方案
- 在评审会上,得到反馈 X是方案中风险最高的
- 你决定先实施X,降低项目风险
- 三天后,你发现X可行性过低
- 你决定暂缓这个项目,优先处理其他工作
整个流程下来,我们花了8天时间发现问题并确定暂缓项目。如果没有设计文档这一流程,可能得浪费更多时间成本才发现问题。