我所理解的各种文档

在软件编写的过程中，文档是其中非常重要的一环，并占据了整个软件开发的大部分时间，在这里我不想去讨论文档对程序编写如何重要，我只想研究一下在软件编写过程中有哪些类型的文档，这些文档都应该写什么。一个程序员通常都不怕写代码，却往往怕写文档，这其中有文笔不好之类的原因外，其中有一个很重要的原因是不知道这些文档是用来干什么，也不知道这些文档该写一些什么。今天在阅读一些相关文档模板的时候有些想法，现在把它们记录下，以备今后所用。

1 需求规格说明书

需求规格说明书（以下称：需求文档）是一个很重要的文档，是在软件交付使用的时候必须提交的一份文档，并且之前这份文档必须由用户确认过。需求文档的原始素材来源于需求分析人员与客户的交流，另一部分就来源于需求分析人员根据经验对原始素材挖掘与扩展。需求文档决定了软件系统的结构与走向，是整个软件项目的基石，如果需求文档存在问题，那么整个软件必然有问题，同时需求文档是其它文档生成的依据。那么求文档该如何写，以及书写的内容该是什么呢?

需求文档的内容不是凭空编写，不是闭门造车造出来的，而是与客户交流所得出的。需求文档编写的过程实际是与客户交流的一个过程，即需求调研过程。如何进行一个需求调研过程呢，需求调研有很多方法，但对于我说，都不是十分很清楚，我这里有一个想法，就是你不管用什么方法，只要你依据一份需求文档模板将里面的每一项与客户交流逐一确认清楚就可以当作完成了调研的过程。这里我想以中国电信的需求规格说明书来说明这一调研过程：

1 引言

1.1 编写目的

此项不需要与用户确认，根据实际写明为什么编写此文档，不过通常编写需求文档的原因都大同小异。

1.2 背景

此项不需要与用户确认，一般可以根据用户提供材料来获取与提炼

1.3 业务术语

此项不需要专门去询问用户，可以在后续调研的过程中逐一确认

1.4 需求文档编写约定

此项一般不需要与用户确认，只是为了方便文档的编写与组织，多数都是由需求分析人员提供，例如需求优先级别定义，状态定义，需求编号等的定义

1.5 参考资料

根据实际情况填写参考的资料

2 任务概述

2.1 目标

此项需要与用户交流确认，当然你不能直接去问客户目标是什么，你可以与客户谈论相关的话题：开发意图、应用目标、使用范围、项目背景等，尤其要弄清一个问题，这个系统是独立系统，还是与其它系统关联的系统，还是现有系统的一个子系统等

2.2 用户特点

此项需要与用户交流确认，软件由哪几类用户使用，每一类用户的教育水平与技术专长，软件预期使用的频度等与客户交流确认

2.3 假定与约束

列出假定与约束，可与客户交流确认：经费限制、时间限制，主要给后续设计人员参考和资源配置

2.4 需要收集和需求分析过程采用的方法

需要调研过程中所使用方法，有时间需要和用户商量确认怎样的调研方法最适合当前客户

3 需求规定

3.1 系统需求

确认客户对系统的高层次的需要或者说要求，此处你也不能直接去问客户：你高层次的需求是什么？你需求准备相关的话题与客户交流，最后由你来提炼，并最终给客户确认。（我认为这是确认高层需求、抽象需求、潜在需求等的一个方法，关关键在于交流之前的准备工作要做足）

3.2 用户需求

确认用户使用系统时的主要业务流程，就是确认用系统中有哪些用例，这里要反复挖掘，要充分考察现在的业务流程情况。这里的调研过程可以按照这样一个过程来完成：当前的业务由哪几类人来完成，每一类人他们做哪些事

3.3 功能综述

这里是对功能需求的一个概括描述，是由抽象提炼获取的

3.4 功能需求

3.4.1 xxx模块/子系统

3.4.1.1 功能名称：FN_XXX 功能编号：NO_XXX_001

3.4.2 yyy模块/子系统

3.4.2.1

3.5 性能需求

3.6 运行环境需求

3.7 灵活性需求

3.8 可靠性需求

3.9 界面需求

3.10 故障处理需求

3.11 安全性需求

3.12 质量需求

3.13 与其它系统集成需要

3.14 其它专门需求

4 验收与交付

4.1 最终交付的工作产品

4.2 验收准则

4.3 最后的交付时间

2 概要设计说明书

我认为概要设计最主要的工作就是根据需求分析进行模块的划分，并将它细分到功能点，并辅助以模块划分图，典型的用例图来说明。概要设计应该不与具体的一种编程技术相关，做好的概要设计应该能够用任何一种编程技术实现，只是难或易的问题，因此我并不认为概要设计不能细化到功能点，当然这也不是绝对的，在概要设计这个阶段也可以软件的体系结构，命名规范，接口规范，分层结构作一个比较详细的说明，那么此时将可能会有某种技术的倾向，但这并不影响大局。

3 详细设计说明书

我认为详细设计就是在编程，虽然不是写代码但它应该是以一种具体的语言、架构为蓝本来对概要设计的抽象结构进行翻译，以我熟悉的J2EE来说，详细设计的时候你需要设计出前台需要的所有界面及操作方法；控制层每个action的名称，每一个执行方法的名称及出入参说明；业务层每service的名称，每个方法的出入参及说明；持久层每个dao的名称，每个方法出入参的说明。简单来说明有了详细计就有了程序，到时只需要按文档写代码就可以了

4 数据库设计说明书

数据库设计说明书应该是内容相对比较明确的文档，主要是依据需求分析与概要设计来完成数据库的逻辑设计与物理设计，即理清抽象的ER关系图，定义出每一个实体的字段名称、类型、约束以及取值含义