代码未动,文档先行

2020/3/21

现在估计是不可能的了,互联网项目,你说等文档写好了,那促销打折啥的活动早就凉凉了!但是,文档还是要有的,是事后补,还是前期写好,都行,重要的是要养成写文档的好习惯。

非常庆幸自己帝都经历过的几家公司,对文档要求都很严格,让我收益很多。软件研发过程中,要写的文档种类很多,需求规格说明书,软件详细设计说明书,测试报告,上线报告,产品手册,接口文档,数据库设计文档等等,自己都写过,通过写这些文档,让我对于软件研发整个生命周期的理解更加透彻。软件研发过程中,通过各种形式的文档,严格限制了需求和设计的边界,让参与研发的各个角色对于软件的理解,更加一致统一,并且保证了软件的维护质量和效率。

我们先来看看在研发一个传统企业级软件的时候,需要哪些形式的文档。


图一 软件文档控制

可以看出,软件研发的控制过程,从需求到产品发布,以及管理,在细化一下。


图二 软件文档控制

规范和文档模板,评审和周报,以及原型和需求,到手册以及部署文档等等,很全面的保障了软件交付质量。《人月神话》看了三遍,不如所有文档写一遍来的痛快和扎实。

需求规格说明书

这份文档的主要作用是理解软件的作用和约束需求(就是让客户不能随便发散),其重点不是罗列出各种功能性需求,而是设置好需求的边界,以及各种非功能性需求和与其他系统的交互规范。把功能性需求描述清楚,是基本要求,包括每个功能点的业务描述(注意要描述业务的特定上下文),详细操作步骤以及功能点的前置和后置条件,这些基本的功能表达清楚了,才能让研发和测试,以及客户都明白要做什么。可以通过UML图,表格,以及用例图等形式来表达。
现在很多互联网公司,多了一个产品经理的角色,其主要工作就是产品的需求和原型的确定,严格上来说他们都不会在写这种规格说明书了,而是通过原型来直接表达,即画出原型后,在原型页面上直接用文字标注各个关键元素的业务逻辑,很直观的表达方式,但是我觉得,一份完备的需求规格说明书还是很有必要的。


图三 软件需求规格说明书


图四 软件需求规格说明书-用例图

软件详细设计说明书

这份文档的主要目的是研发的规约设计,对于软件的主要模块如何设计,如何定义都有详细的说明。这个阶段一般需要写两份文档,概要设计和详细设计,但是很多公司已经就只要一份详细设计了,有重复的地方。
主要通过概述,业务逻辑,服务接口,数据层接口设计这几个方面来阐述一个系统的详细设计,并通过UML图来完整表达设计。依据此份文档,程序员就可以开始编码了。

模块概述:模块的业务描述,注意,同样需要说清楚这个业务模块的上下文和边界;关键流程的表达,一般通过UML中的状态图的方式来展现
业务逻辑:从界面,到业务功能,到异常处理,到特殊需求处理等都需要描述清楚
服务接口:主要是该模块和其他模块或者其他系统之间的接口描述,包括技术和业务描述
数据层接口:详细描述该模块对应的数据表结构的设计


图五 软件详细设计说明书


图六 软件详细设计说明书-类图

数据库模型设计

主要是pdm文件,以前通常用PowerDesigner来设计整个系统的数据模型,这里设计时需要根据公司具体的数据库设计规范,现在在线工具很多,形成最终的数据模型就行,保证团队内部都认可。在设计时,必须清晰的表达清楚,数据库的编码,版本,以及表的存储引擎,和每个字段的含义,索引,以及表之间的关系等等。


图七 数据模型

软件测试报告

测试是软件交付和上线前最关键的一个环节,一般有测试计划和测试报告两个文档,测试计划详细列举了对软件进行测试的环境、资源以及测试资源和测试方案,其中测试范围列出了本次测试的所有测试用例列表。

测试分为功能性测试和性能测试,测试计划中,主要内容是详细列出每个测试用例的测试详情,包括目的,角色和测试准备等。另外,测试会产生bug,通常bug会由统一的bug管理工具进行管理,无需通过文档形式列出。


图八 测试计划


图九 测试计划-测试用例详情

测试报告是对于软件测试的结果进行的总结性报告,即测试计划中的测试用例测试结果。功能性测试和性能测试可以根据不同的测试工具来进行。


图十 软件测试报告


图十一 软件测试报告-功能测试


图十二 软件测试报告-压力测试

软件产品发布

软件产品发布或者上线,会通过用户手册方式交给用户使用。包括某某系统安装配置手册,和某某系统用户手册。


图十三 安装配置手册


图十四 产品发布-配置说明

项目管理约束文档

在整个产品研发周期中,都会有各种评审和会议,都需要严格记录下来每次会议和评审的结果。列举如下。


图十五 项目管理-周报


图十六 项目管理-评审报告