软件开发设计文档怎么写(如何写好一份软件开发设计文档)

  设计文档-也被称作技术规范和实现手册,描述了你如何去解决一个问题,是确保正确完成工作最有用的工具,其目的是迫使你对设计展开缜密的思考,并收集他人的反馈,进而完善你的想法,同时在软件交付和交接的过程中,能让其他人更通俗易懂的了解之前的设计目的和思路

软件开发设计文档怎么写(如何写好一份软件开发设计文档)

  目录:

  一、什么是软件开发设计文档

  二、为什么要写软件开发设计文档

  三、写软件开发设计文档需要注意些什么

  四、怎么写好一份开发设计文档

  一、什么是软件开发设计文档

  设计文档-也被称作技术规范和实现手册,描述了你如何去解决一个问题,是确保正确完成工作最有用的工具

  一般来说,设计文档的生命周期有如下几个步骤:

  创建并快速迭代-通过不断的思考论证和缜密思考,完善出第一版稳定的文档

  评审(可能有多轮)-头脑风暴,直面他人的疑问,收集他人的反馈和意见,完善文档

  实现和迭代-在发现编码实现和设计有冲突或设计有缺陷时,及时调整更新文档

  维护和学习-随着业务功能不断的变化,应该及时更新文档,以免误导后来接手或阅读的人

  不同的领域的设计文档要求不一样,这里主要介绍软件开发过程的设计文档(可能看起来比较偏后端),其组成部分可能会包含如下几部分:

  概要(时间、地点、人物、背景、方案、备选方案等任务的上下文)

  表结构及其之间的关系(E-R图:实体-联系图Entity Relationship Diagram)

  业务流程图、时序图(按照人操作的维度)

  程序流程图、时序图(按照代码执行的维度)

  接口约定(对外公开的方法、api接口等)

  其他(伪代码、类图、思维导图、泳道流程图,对安全、性能、边界情况、性价比的思考)

  附注(附加的解释和说明、引用资料)

  评审情况

  二、为什么要写软件开发设计文档?

  磨刀不误砍柴工,设计文档是确保正确完成工作最有用的工具,且不应该让写设计文档成为大家工作的负担

  其目的是迫使你对设计展开缜密的思考,并收集他人的反馈,进而完善你的想法

  同时在软件交付和交接的过程中,能让其他人更通俗易懂的了解之前的设计目的和思路

  它是一种知识的沉淀和传承

  我们经常听到这样的话:”设计文档没有用,是用来糊弄客户和管理层的文档“,”用来写设计文档的时间,我的任务早就做完了“,”项目紧张,没有时间做设计“,这种说法是不正确的,对小的功能来说没毛病,但是大的复杂的任务时就很容易出现各种考虑不周、大量BUG、甚至返工的情况,每个团队都应该根据自己的任务周期合理约定文档撰写的内容,什么情况该写什么

  三、写软件开发设计文档需要注意些什么

  我参与过很多次设计评审,经常会发现如下问题:

  文档工具不统一,不同的小组、部门存在差异,有些甚至不知道是什么格式的文件,无法打开

  过度拷贝需求文档,缺少软件设计的内容,不像软件设计文档

  排版混乱,设计文档未按照标准模板顺序,缺少清晰的目录结构

  设计文档太多图片,有些质量很差,且缺失原始文件,比如EA工具做的缺乏eapx文件,会导致文档迭代需要全部重新绘图,久而久之更加不愿意去维护更新文档了

  没有统一的文档版本管理工具,缺少追溯和统计管理的能力

  数据库表结构设计样式杂乱不统一,字段无中文描述(毕竟母语不是英语),且基本没有考虑主键和索引设计

  程序流程基本比较简单,缺少主线,无法描述核心算法及关键点(例如,取款机如何取钱?有些仅仅描述了【插卡->取钱->取卡】是不够的,还应包含各种校验、事务、并发、缓存等处理)

  类图缺乏体现类之间的关系,有的直接用英文函数名,缺乏描述

  时序图大多只描述与数据库的交互,缺少业务流程和程序执行的时序图

  不理解设计文档的意义,很简单的任务需求就不需要写设计文档了

  缺少对安全、性能、边界情况、性价比的思考,考虑还不够全面,评审把关不严

  总结了几点需要注意的问题给大家参考参考:

  文档撰写人:架构设计师或功能的开发者

  明确文档面向的读者:是部门内部的开发者?伙伴实施人员?外部的开发者?

  设计先行:设计文档在撰写应该是在编码之前,可以极大地避免后期出现返工的情况,也能提升开发效率

  一图胜千言:尽可能地使用图文的方式表达清楚设计思路

  统一的绘图工具:需要支持导入及导出,方便后续更新

  统一的文档模板:为了防止出现千奇百怪的文档、排版不一致、难以阅读等的问题

  确定承载的形式:可以从安全性(文档加密)、便于查看、版本管理等方面考虑,推荐内部的知识文档管理系统、类似wikigitsvn的版本管理工具、内网微盘

  好代码优于设计文档:有时候写出优雅的代码和注释更胜于写一篇设计文档

  版本迭代:在软件功能迭代的过程中,可能经过几次迭代后功能和设计有了很大的变化,设计文档应该及时更新,以免给人传递错误的信息

  四、怎么写好一份开发设计文档

  用什么工具

  1、推荐开源的绘图工具:https://www.draw.io/?lang=zh

软件开发设计文档怎么写(如何写好一份软件开发设计文档)

  2、word(设计文档模板,也可以使用wikiconfluence这类团队工作空间管理工具)

  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、放一波预览图(样例,仅供参考):

软件开发设计文档怎么写(如何写好一份软件开发设计文档)
软件开发设计文档怎么写(如何写好一份软件开发设计文档)
软件开发设计文档怎么写(如何写好一份软件开发设计文档)
软件开发设计文档怎么写(如何写好一份软件开发设计文档)
软件开发设计文档怎么写(如何写好一份软件开发设计文档)
软件开发设计文档怎么写(如何写好一份软件开发设计文档)

如若转载,请注明出处:纯敬科技https://www.purexm.com/article/677.html

发表评论

电子邮件地址不会被公开。 必填项已用*标注