设计文档 - 也被称作技术规范和实现手册，描述了你如何去解决一个问题，是确保正确完成工作最有用的工具，其目的是迫使你对设计展开缜密的思考，并收集他人的反馈，进而完善你的想法，同时在软件交付和交接的过程中，能让其他人更通俗易懂的了解之前的设计目的和思路
目录：
- 一、什么是软件开发设计文档
- 二、为什么要写软件开发设计文档
- 三、写软件开发设计文档需要注意些什么
- 四、怎么写好一份开发设计文档
一、什么是软件开发设计文档
- 设计文档 - 也被称作技术规范和实现手册，描述了你如何去解决一个问题，是确保正确完成工作最有用的工具
- 一般来说，设计文档的生命周期有如下几个步骤：
- 创建并快速迭代 - 通过不断的思考论证和缜密思考，完善出第一版稳定的文档
- 评审（可能有多轮） - 头脑风暴，直面他人的疑问，收集他人的反馈和意见，完善文档
- 实现和迭代 - 在发现编码实现和设计有冲突或设计有缺陷时，及时调整更新文档
- 维护和学习 - 随着业务功能不断的变化，应该及时更新文档，以免误导后来接手或阅读的人
- 不同的领域的设计文档要求不一样，这里主要介绍软件开发过程的设计文档（可能看起来比较偏后端），其组成部分可能会包含如下几部分：
- 概要 （时间、地点、人物、背景、方案、备选方案等任务的上下文）
- 表结构及其之间的关系（E-R 图：实体-联系图 Entity Relationship Diagram）
- 业务流程图、时序图（按照人操作的维度）
- 程序流程图、时序图（按照代码执行的维度）
- 接口约定（对外公开的方法、api 接口等）
- 其他（伪代码、类图、思维导图、泳道流程图，对安全、性能、边界情况、性价比的思考）
- 附注（附加的解释和说明、引用资料）
- 评审情况
二、为什么要写软件开发设计文档？
- 磨刀不误砍柴工，设计文档是确保正确完成工作最有用的工具，且不应该让写设计文档成为大家工作的负担
- 其目的是迫使你对设计展开缜密的思考，并收集他人的反馈，进而完善你的想法
- 同时在软件交付和交接的过程中，能让其他人更通俗易懂的了解之前的设计目的和思路
- 它是一种知识的沉淀和传承
- 我们经常听到这样的话：”设计文档没有用，是用来糊弄客户和管理层的文档“，”用来写设计文档的时间，我的任务早就做完了“，”项目紧张，没有时间做设计“，这种说法是不正确的，对小的功能来说没毛病，但是大的复杂的任务时就很容易出现各种考虑不周、大量 BUG、甚至返工的情况，每个团队都应该根据自己的任务周期合理约定文档撰写的内容，什么情况该写什么
三、写软件开发设计文档需要注意些什么
- 我参与过很多次设计评审，经常会发现如下问题：
- 文档工具不统一，不同的小组、部门存在差异，有些甚至不知道是什么格式的文件，无法打开
- 过度拷贝需求文档，缺少软件设计的内容，不像软件设计文档
- 排版混乱，设计文档未按照标准模板顺序，缺少清晰的目录结构
- 设计文档太多图片，有些质量很差，且缺失原始文件，比如 EA 工具做的缺乏 eapx 文件，会导致文档迭代需要全部重新绘图，久而久之更加不愿意去维护更新文档了
- 没有统一的文档版本管理工具，缺少追溯和统计管理的能力
- 数据库表结构设计样式杂乱不统一，字段无中文描述（毕竟母语不是英语），且基本没有考虑主键和索引设计
- 程序流程基本比较简单，缺少主线，无法描述核心算法及关键点 （例如，取款机如何取钱？有些仅仅描述了【插卡 -> 取钱 -> 取卡】是不够的，还应包含各种校验、事务、并发、缓存等处理）
- 类图缺乏体现类之间的关系，有的直接用英文函数名，缺乏描述
- 时序图大多只描述与数据库的交互，缺少业务流程和程序执行的时序图
- 不理解设计文档的意义，很简单的任务需求就不需要写设计文档了
- 缺少对安全、性能、边界情况、性价比的思考，考虑还不够全面，评审把关不严
- 总结了几点需要注意的问题给大家参考参考：
- 文档撰写人：架构设计师或功能的开发者
- 明确文档面向的读者：是部门内部的开发者？伙伴实施人员？外部的开发者？
- 设计先行：设计文档在撰写应该是在编码之前，可以极大地避免后期出现返工的情况，也能提升开发效率
- 一图胜千言：尽可能地使用图文的方式表达清楚设计思路
- 统一的绘图工具：需要支持导入及导出，方便后续更新
- 统一的文档模板：为了防止出现千奇百怪的文档、排版不一致、难以阅读等的问题
- 确定承载的形式：可以从安全性（文档加密）、便于查看、版本管理等方面考虑，推荐内部的知识文档管理系统、类似 wiki \ git \ svn 的版本管理工具、内网微盘
- 好代码优于设计文档：有时候写出优雅的代码和注释更胜于写一篇设计文档
- 版本迭代：在软件功能迭代的过程中，可能经过几次迭代后功能和设计有了很大的变化，设计文档应该及时更新，以免给人传递错误的信息
四、怎么写好一份开发设计文档
- 用什么工具
1、推荐开源的绘图工具：https://www.draw.io/?lang=zh
官网截的图
2、word （设计文档模板，也可以使用 wiki \ confluence 这类团队工作空间管理工具）
3、xMind （画思维导图）
4、visio （画图工具，目前没发现有 mac 版的）
- 如何写、如何画？
1、下一篇我将介绍如何用 draw.io 画图（时序图、流程图、类图、ER 图、架构图）
2、列举了一些参考资料：
▶ 流程图：http://www.woshipm.com/zhichang/2329530.html
▶ 时序图：http://www.woshipm.com/ucd/607593.html
▶ 类图：https://design-patterns.readthedocs.io/zh_CN/latest/read_uml.html
▶ 程序流程图 https://cn.vuejs.org/v2/guide/instance.html#生命周期图示
3、放一波预览图（样例，仅供参考）：
扫一扫
2413
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
