代码未动，文档先行

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

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

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

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

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

这份文档的主要作用是理解软件的作用和约束需求（就是让客户不能随便发散），其重点不是罗列出各种功能性需求，而是设置好需求的边界，以及各种非功能性需求和与其他系统的交互规范。把功能性需求描述清楚，是基本要求，包括每个功能点的业务描述（注意要描述业务的特定上下文），详细操作步骤以及功能点的前置和后置条件，这些基本的功能表达清楚了，才能让研发和测试，以及客户都明白要做什么。可以通过UML图，表格，以及用例图等形式来表达。

现在很多互联网公司，多了一个产品经理的角色，其主要工作就是产品的需求和原型的确定，严格上来说他们都不会在写这种规格说明书了，而是通过原型来直接表达，即画出原型后，在原型页面上直接用文字标注各个关键元素的业务逻辑，很直观的表达方式，但是我觉得，一份完备的需求规格说明书还是很有必要的。

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

模块概述

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

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

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

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

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

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