软件文档编写向导
文档分类
项目包括如下几类文档；
项目管理文档。包括：《软件项目计划》、《项目进度报告》、《项目开发总结报告》
软件开发文档。包括：《需求规格说明》、《概要设计说明》、《详细设计说明》。
软件测试文档。包括：《测试计划》、《软件测试分析报告》。
产品资料。包括：《用户操作手册》。
文档的版本号
本项目文档的版本号由以圆点隔开的两个数字组成，第一个数字表示出版号，第二个数字表示该版的修订号。具体用法如下：
当文档初版时，版本号为
V1.0
；
当文档被局部修订时，出版号不变，修订号增
1
。例如，对初版文档作了第一次修订，则版本号为
V1.1
；
当文档被全面改写或局部修订累积较多导致文档发生全局变化时，出版号增
1
。例如，在
V1.5
版的基础上作了一次全面修订，则新版本号为
V2.0
。
文档的标识
项目所产生的文档都有唯一、特定的编码，其构成如下：
项目标志
-
任务标识
-
文档类型
-
文档树中的编号
-
版本号
/
序号
其中：
项目标志：本项目的标识，表明本项目是“
XXXX
”。
任务标识：少于八个字母，简要标识本任务，标准
XXXX
是“
STANDARD
”。适用于整个项目的文档，此标识为“
XXXX
”。
文档类型：取自下表的两位字母编码。
编号：反映文档类型（根据下表填写）
版本号：本文档的版本号。
序号：四位数字编码，指明该文档在项目文档库的总序号。
一个文档编码的例子为：
XXXX-XXXX-SP-2N01-V1.0/0015
表
5.3
项目的文档分类表
|
文
档
类
型
|
编码
|
编号
|
注
释
|
|
|
项目管理
|
项目开发计划
|
PP
|
1002
|
Project Plan
|
|
项目进度报告
|
PR
|
1003
|
Project Report
|
|
|
软件开发
|
软件项目计划
|
SP
|
2N01
|
Software Plan
|
|
软件需求规格说明
|
SA
|
2N02
|
Software Anlaysis
|
|
|
软件设计说明
|
SD
|
2N03
|
Software Design
|
|
|
软件测试
|
软件测试计划
|
TP
|
4N01
|
Testing Plan
|
|
软件测试分析报告
|
TR
|
4N02
|
Tesing Report
|
|
|
产品文档
|
用户手册
|
RU
|
5N01
|
User guide
|
本项目中所有文档的标识清单将在《项目开发计划》中予以具体定义。
文档的编写模板
本项目中所有任务的文档将按照统一的模板（格式和内容的约定）来编写，包括：
《模板
-
软件开发计划》
《模板
-
软件需求规格说明》
《模板
-
软件设计说明》
《模板
-
技术说明》
文档的模板均保存在配置管理员处，并由其分发给文档的编写者。
需要说明的是，文档模板是本项目在文档结构和版式上的统一约定，对于具体文档，编写者可以根据需要添加章节，原则上不要删除章节（可以写“本章
/
节无内容”）。当文档模板不符合编写者要求时，编写者应与项目组长联系以决定文档的编写标准。
关于《技术说明》
在
产品包中，应包含一份《技术说明》，以详细说明本产品的代码来源和修改情况。
在《技术说明》中，应包含如下内容：
代码包的清单，格式为：
|
代码包名
|
来源
|
版本
|
功能的描述
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
其中，“来源”可以是：下载的网络地址、“拷贝”、“创建”
代码文件的清单，格式为：
|
代码包名
|
文件名
|
状态
|
修改者
/
作者
|
最后修改时间
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
其中，“状态”可以是：“修改”、“删除”、“创建”、“原样”
封面格式：
文档编号
版
本
号
文档名称：
项目名称：
项目负责人：
编写
年
月
日
校对
年
月
日
审核
年
月
日
批准
年
月
日
开发单位
系统规格说明书（
System Specification
）
一．引言
A.
文档的范围和目的
B.
概述
1
．目标
二．功能和数据描述
A.
系统结构
1
．结构关系图
2
．结构关系图描述
三．子系统描述
A.
子系统的结构图规格说明
B.
结构字典
C.
结构连接图和说明
四．系统建模和模拟结构
A.
用于模拟的系统模型
B.
模拟结果
C.
特殊性能
五．软件项目问题
A.
软件项目计划
六．附录
软件项目计划（
Software Project Plan
）
一．引言
1
．编写目的（阐明编写软件计划的目的，指出读者对象。）
2
．项目背景（可包括：（
1
）项目委托单位、开发单位和主管部门；（
2
）该软件系统与其他系统的关系。）
3
．定义（列出本文档中用到的专门术语的定义和缩略词的原文。）
4
．参考资料（可包括：文档所引用的资料、规范等；列出资料的作者、标题、编号、发表日期、出版单位或资料来源。）
二．项目概述
1.
工作内容（简要说明项目的各项主要工作
,
介绍所开发软件的功能
性能等
.
若不编写可行性研究报告
,
则应在本节给出较详细的介绍。
)
2.
条件与限制（阐明为完成项目应具备的条件
开发单位已具备的条件以及尚需创造的条件
.
必要时还应说明用户及分合同承包者承担的工作
完成期限及其它条件与限制。）
3.
产品
（
1
）程序（列出应交付的程序名称
使用的语言及存储形式。）
（
2
）文档（列出应交付的文档。）
（
3
）运行环境（应包括硬件环境
软件环境。）
4
．服务（阐明开发单位可向用户提供的服务
.
如人员培训
安装
保修
维护和其他运行支持。）
5
．验收标准
三．实施计划
1
．任务分解（任务的划分及各项任务的负责人。）
2
．进度（按阶段完成的项目
,
用图表说明开始时间
完成时间。）
3
．预算
4
．关键问题（说明可能影响项目的关键问题
,
如设备条件
技术难点或其他风险因素
,
并说明对策。）
四．人员组织及分工
五．交付期限
六．专题计划要点（如测试计划等。）
需求规格说明书（
Requirements Specification
）
一．引言
1
．
编写目的（阐明编写需求说明书的目的
,
指明读者对象。）
2
．
项目背景（可包括：（
1
）项目的委托单位
,
开发单位和主管部门；（
2
）该软件系统与其他系统的关系。）
3
．
定义（列出文档中用到的专门术语定义和缩写词的原文。）
4
．
参考资料（可包括：（
1
）项目开发计划；（
2
）文档所引用的资料，标准和规范。列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源。）
二．任务概述
1
．目标
2
．运行环境
3
．条件与限制
三．数据描述
1
．
静态数据
2
．
动态数据（包括输入数据和输出数据。）
3
．
数据库描述（给出使用数据库的名称和类型。）
4
．
数据词典
5
．
数据采集
四．功能需求
1
．功能划分
2
．功能描述
五．性能需求
1
．数据精确度
2
．时间特性（如响应时间、更新处理时间、数据转化与传输时间、运行时间等。）
3
．适应性（在操作方式
运行环境
与其他软件的接口以及开发计划等发生变化时，应具有的适应能力。）
六．运行需求
1
．用户界面（如屏幕格式、报表格式、菜单格式、输入输出时间等。）
2
．硬件接口
3
．软件接口
4
．故障处理
七．其他需求（如可使用性、安全保密、可维护性、可移植性等。）
概要设计说明书（
Architectural Design Specification
）
一．引言
1
．编写目的（阐明编写概要设计说明书的目的，指明读者对象。）
2
．项目背景（可包括：（
1
）项目的委托单位
,
开发单位和主管部门；（
2
）该软件系统与其他系统的关系。）
3
．定义（列出文档中用到的专门术语定义和缩写词的原意。）
4
．参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）测试计划（初稿）；（
4
）用户操作手册（初稿）；（
5
）文档所引用的资料、采用的标准或规范。）
二．任务概述
1
．目标
2
．运行环境
3
．需求概述
4
．条件与限制
三．总体设计
1
．处理流程
2
．总体结构和模块外部设计
3
．功能分配（表明各项功能与程序结构的关系。）
四．接口设计
1
．外部接口（包括用户界面
软件接口与硬件接口。）
2
．内部接口（模块之间的接口。）
五．数据结构设计
1
．
逻辑结构设计
2
．
物理结构设计
3
．
数据结构与程序的关系
六．运行设计
1
．运行模块的组合
2
．运行控制
3
．运行时间
七．出错处理设计
1
．出错输出信息
2
．出错处理对策（如设置后备、性能降级、恢复及再启动等。）
八．安全保密设计
九．维护设计（说明为方便维护工作的设施
,
如维护模块等。）
详细设计说明书（
Procedural Design Specification
）
一．引言
1
．
编写目的（阐明编写详细设计说明书的目的
,
指明读者对象。）
2
．
项目背景（应包括项目的来源和主管部门等。）
3
．
定义（列出文档中用到的专门术语定义和缩写词的原意。）
4
．
参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）概要设计说明书；（
4
）测试计划
(
初稿
)
；（
5
）用户操作手册
(
初稿
)
；（
5
）文档所引用的其他资料、软件开发标准或规范。）
二．总体设计
1
．需求概述
2
．软件结构（如给出软件系统的结果图。）
三．程序描述（逐个模块给出以下的说明
:
：）
1
．功能
2
．性能
3
．输入项目
4
．输出项目
5
．算法（模块所选用的算法。）
6
．程序逻辑（详细描述模块实现的算法，可采用
:
：（
1
）标准流程图；（
2
）
N-S
图；（
3
）
PAD
；（
4
）判定表等描述算法的图表。）
7
．接口
8
．存储分配
9
．限制条件
10
．
测试要点（给出测试模块的主要测试要求。）
用户操作手册（
User Guide
）
一．引言
1
．编写目的（阐明编写手册的目的，指明读者对象。）
2
．项目背景（说明项目的来源、委托单位、开发单位及主管部门。）
3
．定义（列出手册中用到的专门术语定义和缩写词的原意。）
4
．参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）概要设计说明书；（
4
）详细设计说明书；（
5
）测试计划；（
6
）手册中引用的其他资料、采用的软件工程标准或软件工程规范。）
二．软件概述
1
．目标
2
．功能
3
．性能
（
1
）数据精确度（包括输入、输出及处理数据的精度。）
（
2
）时间特性（如响应时间、处理时间、数据传输时间等。）
（
3
）灵活性（在操作方式、运行环境需做某些变更时软件的适应能力。）
三．运行环境
1
．硬件（列出软件系统运行时所需的硬件最小配置，如：（
1
）计算机型号、主存容量；（
2
）外存储器、媒体、记录格式、设备型号及数量；（
3
）输入、输出设备；（
4
）数据传输设备及数据转换设备的型号及数量。）
2
．支持软件（如：（
1
）操作系统名称及版本号；（
2
）语言编译系统或汇编系统的名称及版本号；（
3
）数据库管理系统的名称及版本号；（
4
）其他必要的支持软件。）
四．使用说明
1
．安装和初始化（给出程序的存储形式、操作命令、反馈信息及其含义、表明安装完成的测试实例以及安装所需的软件工具等。）
2
．输入（给出输入数据或参数的要求。）
（
1
）数据背景（说明数据来源、存储媒体、出现频度、限制和质量管理等。）
（
2
）数据格式（如：（
1
）长度（
2
）格式基准（
3
）标号（
4
）顺序（
5
）分隔符（
6
）词汇表（
7
）省略和重复（
8
）控制。）
（
3
）输入举例
3
．输出（给出每项输出数据的说明。）
（
1
）数据背景（说明输出数据的去向、使用频度、存放媒体及质量管理等。）
（
2
）数据格式（详细阐明每一输出数据的格式
,
如
:
首部
主体和尾部的具体形式。）
（
3
）举例
3
．出错和恢复（给出：（
1
）出错信息及其含义（
2
）用户应采取的措施，如修改、恢复、再启动。）
4
．求助查询（说明如何操作。）
五．运行说明
1
．
运行表
[
列出每种可能的运行情况
,
说明其运行目的
.]
2
．
运行步骤
[
按顺序说明每种运行的步骤
,
应包括
:]
（
1
）
运行控制
（
2
）
操作信息（（
1
）运行目的（
2
）操作要求（
3
）启动方法（
4
）预计运行时间（
5
）操作命令格式及说明（
6
）其他事项。）
（
3
）
输入
/
输出文件（给出建立和更新文件的有关信息，如：（
1
）文件的名称及编号（
2
）记录媒体（
3
）存留的目录（
4
）文件的支配
[
说明确定保留文件或废弃文件的准则，分发文件的对象，占用硬件的优先级及保密控制等。）
（
4
）
启动或恢复过程
六．非常规过程（提供应急或非常规操作的必要信息及操作步骤，如出错处理操作、向后备系统切换操作以及维护人员须知的操作和注意事项。）
七．操作命令一览表
（按字母顺序逐个列出全部操作命令的格式
功能及参数说明。）
八．程序文件（或命令文件）和数据文件一览表（按文件名字母顺序或按功能与模块分类顺序逐个列出文件名称、标识符及说明。）
九．用户操作举例
测试计划（
Test Plan
）
一、引言
1
．
编写目的（阐明编写测试计划的目的
,
指明读者对象。）
2
．
项目背景（说明项目的来源
委托单位及主管部门。）
3
．
定义（列出测试计划中用到的专门术语定义和缩写词的原意。）
4
．
参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）概要设计说明书；（
4
）详细设计说明书；（
5
）用户操作手册
; (6)
本测试计划中引用的其他资料
采用的软件开发标准或规范。）
二．任务概述
1
．目标
2
．运行环境
3
．需求概述
4
．条件与限制
三．计划
1
．测试方案（说明确定测试方法和选取测试用例的原则。）
2
．测试项目（列出组装测试和确认测试中每一项测试的内容、名称、目的和进度。）
3
．测试准备
4
．测试机构及人员（测试机构名称
负责人和职责。）
四．测试项目说明（按顺序逐个对测试项目做出说明：）
1
．测试项目名称及测试内容
2
．测试用例
（
1
）输入（输入的数据和输入的命令。）
（
2
）输出（预期的输出数据。）
（
3
）步骤及操作
（
4
）允许偏差（给出实测结果与预测结果之间允许偏差的范围。）
3
．
进度
4
．
条件（给出项测试对资源的特殊要求，如设备、软件、人员等。）
5
．
测试资料（说明项测试所需的资料。）
五．评价
1
．范围（说明所完成的各项测试说明问题的范围及其局限性。）
2
．准则（说明评价测试结果的准则。）
测试分析报告（
Test Specification
）
一．引言
1
．编写目的（阐明编写测试分析报告的目的，指明读者对象。）
2
．项目背景（说明项目的来源、委托单位及主管部门。）
3
．定义（列出测试分析报告中用到的专门术语定义和缩写词的原意。）
4
．参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）概要设计说明书；（
4
）详细设计说明书；（
5
）用户操作手册；（
6
）测试计划；（
7
）测试分析报告所引用的其他资料、采用的软件工程标准或软件工程规范。）
二．测试计划执行情况
1
．测试项目（列出每一测试项目的名称、内容和目的。）
2
．测试机构和人员（给出测试机构名称、负责人和参与测试人员名单。）
3
．测试结果（按顺序给出每一测试项目的：（
1
）实测结果数据（
2
）与预期结果数据的偏差（
3
）该项测试说明的事实（
4
）该项测试发现的问题。）
三．软件需求测试结论（按顺序给出每一项需求测试的结论。包括：（
1
）证实的软件能力（
2
）局限性（即项需求未得到充分测试的情况及原因）。）
四．评价
1
．软件能力（经过测试所表明的软件能力。）
2
．缺陷和限制（说明测试所揭露的软件缺陷和不足
,
以及可能给软件运行带来的影响。）
3
．建议（提出为弥补上述缺陷的建议。）
4
．测试结论（说明能否通过。）
开发进度报告
一．报告时间及所处的开发阶段
二．给出进度
1
．
本周的主要活动
2
．
实际进展与计划比较
三．所用工时（按不同层次人员分别计时。）
四．所有机时
五．工作遇到的问题及采取的对策
六．本周完成的成果
七．下周的工作计划
八．特殊问题
项目开发总结报告
(
包括以该报告为基础编写一篇
ppt
文档，以供项目结束时参加项目答辩
)
一．引言
1
．编写目的（阐明编写总结报告的目的
,
指明读者对象。）
2
．项目背景（说明项目的来源、委托单位、开发单位及主管部门。）
3
．定义（列出报告中用到的专门术语定义和缩写词的原意。）
4
．参考资料（列出这些资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：（
1
）项目开发计划；（
2
）需求规格说明书；（
3
）概要设计说明书；（
4
）详细设计说明书；（
5
）用户操作手册；（
6
）测试计划；（
7
）测试分析报告（
8
）本报告引用的其他资料、采用的开发标准或开发规范。）
二．开发结果
1
．
产品（可包括：（
1
）列出各部分的程序名称、源程序行数（包括注释行）或目标程序字节数及程序总计数量、存储形式；产品文档名称等。）
2
．
主要功能及性能
3
．
所用工时（按人员的不同层次分别计时。）
4
．
所用机时
5
．
进度（给出计划进度与实际进度的对比。）
三．评价
1
．生产率评价（如平均每人每周源程序行数、文档的字数等。）
2
．技术方案评价
3
．产品质量评价
四．经验与教训
转载自：http://blog.csdn.net/ddscorpio/archive/2006/12/09/1436440.aspx
转载自：http://blog.csdn.net/ddscorpio/archive/2006/12/09/1436440.aspx