014软件开发技术文档管理规范

目录

1.

前言 ...................................................................................................................................................................1 1.1 1.2 1.3 1.4 2.

目的 .....................................................................................................................................................1 术语 .....................................................................................................................................................1 参考文献.............................................................................................................................................1 版本说明和修改历史 ......................................................................................................................1

软件文档...........................................................................................................................................................1 2.1 2.2 2.3 2.4

文档的定义及作用...........................................................................................................................1 软件文档的分类 ...............................................................................................................................2 软件文档的制作与软件生存周期之间的关系 . .........................................................................3 文档的使用者....................................................................................................................................3

3. 文档编制格式规范.........................................................................................................................................4 3.1 3.2 3.2.1 3.2.2 3.2.3 3.2.4 3.2.5 3.3

文档编码规则....................................................................................................................................4 文档组成格式....................................................................................................................................4

封面 .......................................................................................................................................5 目录 .......................................................................................................................................6 版本更新说明......................................................................................................................6 文件内容...............................................................................................................................6 正文格式...............................................................................................................................7

文档制作工具....................................................................................................................................7

4. 文档管理规范..................................................................................................................................................7 4.1 4.2 4.2.1 4.2.2 4.3 4.4 4.5 4.6 4.7 4.8

文档管理岗位职责...........................................................................................................................7 文档的制作 . .......................................................................................................................................8

文档的分类、编码与标识 ...............................................................................................8 文档的作者、修改者和打字者.......................................................................................8

文档的收集 . .......................................................................................................................................8 文档的配置 . .......................................................................................................................................9 文档的控制 . .......................................................................................................................................9 文档的修改管理 ...............................................................................................................................9 文档的借阅和复制管理制度 . ......................................................................................................10 文档的保密性..................................................................................................................................10

5. 技术文档的质量评价 ..................................................................................................................................11

1. 前言

1.1 目的

软件开发的不同阶段都会产生大量的文档。为了加强管理、提高工作效率，充分借鉴前人的经验，对文档进行规范化管理是很有必要的。它对于保管在开发中形成的文档，为公司积累宝贵的技术知识的财富，为今后的软件开发工作提供第一手的宝贵资料起着重要的作用。

为了规范创智集团工程项目的开发工作，根据国家标准局制定的有关软件开发和开发文件的规范标准，结合公司的实际，制定本规范。

1.2 术语

略。

1.3 参考文献

1) 《1998计算机软件工程规范----国家标准》 中国标准出版社 1998年

6月第一版。

2) 《软件工程概论》 郑人杰等 清华大学出版社 1998年4月第一版。 3) 《实用软件工程》 郑人杰等 清华大学出版社 1997年4月第二版。 4) 《创智软件园文档管理规范》 创智（湖南）软件园有限公司 1996年

5月。

5) 《创智软件园软件开发管理规范》 创智（湖南）软件园有限公司 1995

年12月。

1.4 版本说明和修改历史

本规范是在公司原有文档规范的基础上，于1999年05月份修订而成，具体的修订人员为孙继纲、赵海等。

2. 软件文档

2.1 文档的定义及作用

文档（document ）是指某种数据媒体和其中所记录的数据。它具有永久性，

并可以由人或机器阅读，通常仅用于描述人工可读的东西。

正确地制作和使用软件文档，可以获得如下的便利：

● 提高软件开发过程的能见度。 ● 提高开发效率。

● 作为开发人员在一定阶段的工作成果和结束标志。

● 记录开发过程中的有关信息，便于协调以后的软件、开发、使用和

维护。

● 便于潜在用户了解软件的功能、性能等各项指标，为他们选购符合

自己需要的软件提供依据。

2.2 软件文档的分类

对于软件文档的分类有多种方法。 从形式上分为两类：

● 开发过程中可以填写的各种图表，可称之为工作表格。

● 应编制的技术资料或技术管理资料，可称之为文档或文件。 按照软件文档的产生和使用范围可以分为三类：

● 开发文档：软件开发过程中，作为软件开发人员前一阶段工作成果

的体现和后一阶段工作依据的文档。包括可行性研究、项目开发计划、需求说明、数据说明、概要设计和详细设计。

● 管理文档：软件开发过程中，由软件开发人员制定的需提交管理人

员的一些工作计划和工作报告，包括项目开发计划、测试计划、测试报告、开发进度月报及项目开发总结。

● 用户文档：软件开发人员为用户准备的有关该软件使用、操作、维

护的资料，包括用户手册、操作手册、维护修改建议、需求说明。

按照计算机软件产品开发文件编制指南的国家标准（GB8567-88）的要求，在一项计算机软件的开发过程中，一般地说，应该产生14种文件：

● 可行性研究报告。 ● 项目开发计划。 ● 软件需求说明书。 ● 数据要求说明书。 ● 概要设计说明书。 ● 详细设计说明书。 ● 数据库设计说明书。 ● 用户手册。 ● 操作手册。

● 模块开发卷宗。 ● 测试计划。

● 测试分析报告。 ● 开发进度月报。

● 项目开发总结报告。

2.3 软件文档的制作与软件生存周期之间的关系

一般而言，计算机软件生存周期可以分为六个阶段：

● 可行性与计划研究阶段。 ● 需求分析阶段。 ● 设计阶段。 ● 实现阶段。 ● 测试阶段。

● 运行与维护阶段。

2.4 文档的使用者

对于软件文档的使用人员而言，与其所承担的工作有关，具体情况如下所示。 管理人员：

● 可行性研究报告。 ● 项目开发计划书。 ● 模块开发卷宗。 ● 开发进度月报。

● 项目开发总结报告。

开发人员：

● 可行性研究报告。 ● 项目开发计划书。 ● 需求分析说明书。 ● 概要设计说明书

● 详细设计说明书

● 数据库设计说明书。 ● 测试计划。

● 测试分析报告。

维护人员：

● 设计说明书。 ● 测试分析报告。 ● 模块开发卷宗。 ●

最终用户：

● 系统安装手册。 ● 用户手册。

● 系统维护手册。 ● 系统功能说明书

3. 文档编制格式规范

3.1 文档编码规则

公司所有的技术文档，都必须具有一个唯一的系列号，格式为： PRS-PID-XX：

1) “PRS ”：创智标识符（Company Flag)。 2) “PID ”：项目代号。 3) “XX ”：文档标识号，参见《软件开发配置管理规程》。

例如，文件号：PRS-PowerOffice-MD-01-1.0.0

表示：该文件由本公司产品PowerOffice ，MD 表示是管理文档，001表示是项目开发计划书，版本号1.0.0表示是PowerOffice 产品1.0.0版。

3.2 文档组成格式

公司所有文档（仅一页的文件可按单页文档格式组织）由封面、目录（Content Table) 、版本更新说明书（Rivision) 、文件内容等组成，如图所示

参考文献附录

封面

目录

版本说明

文件内容

名词索引

图1文档组成档式

3.2.1 封面

封面组成可划分为：

1. 文档号：DOC.NO. 文档系列号 (文档文件名)

字体: Arial , 小四, 加粗

例：DOC.NO. PRS-PID-XX (Facedoc.doc) 2. 项目名称: 中文字体: 黑体, 三号字体, 加粗

英文字体: Arial , 三号字体, 加粗

例：创智文档规范

3. 文档名称: 中文字体：黑体, 一号字体, 加粗

英文字体：Arial, 一号字体, 加粗

例：

工程技术项目文档规范

4. 密级：英文字体: Arial, 小四字体, 加粗

划分为五类，采用下列关键词

Top Confidential High Confidential Confidential Normal General

● Top Confidential：绝密

产品文档

● High Confidential：机密

规范、指南

● Confidential ：秘密

计划、管理 ● Normal ：普通

工作岗位有关 ● General ：明文

可以在社会上广为流传 例 : Normal

5. 版本号：关键词为 Version 用 Arial 字体, 大小为小四号

例: Version V1.0.0

6. 完成日期：用Arial 字体, 大小为小四号

例: 1994.11.14.

7. 作者：Written By„„用 Arial 字体, 大小为小四号, 加粗

例: Written By POWERISE

8. 公司LOGO: 用 USABLack 字体, 大小为四号, 加粗。

例: POWERISE

9. 公司名称及版权生效年份:

关键词为：创智软件园有限公司

Powerise Software. Inc. 版权生效年限：关键词为（C ）公历年号

中文字体: 黑体, 四号, 加粗

例: 创智软件园有限公司 (C)1994,1999

注：此处填写产品已经经过的年份，如PowerLCMS,copyrights(C)1996,1998. 英文字体: Arial , 四号, 加粗

例: Powerise Software.Inc.(C)1994,1995

10. 版权申明：字体为: Arial , 小四, 加粗

例: All Right Reserved

各项安排如下图, 样板范例可参见本文档的封面：

1

2

3

5

79

3.2.2 目录

可采用手工编制或使用文档编制 Microsoft Word 的自动生成目录的功能产生文档目录。

3.2.3 版本更新说明

关键词为：Revision 内容划分为：日期(Date)、理由(Reason)、更新者(Revisor)。(首版可省略该节)

3.2.4 文件内容

文件内容每一页必须包含下列三项，缺一不可：

● 页首，在页首中部自动填入‘标题1’的名称。

● 页脚，在页脚左部填入创智标徽POWERISE ，右部填入页号。 ● 正文。

如下图所示，具体设置可复制本文作模块。

3.2.5 正文格式

标题一：宋体、小三、粗体，左对齐； 标题二：黑体、四号、粗体，左对齐； 标题三：宋体、小四号、粗体，左对齐； 标题四：黑体、小四号、正常体，左对齐； 标题五：黑体、五号、粗体，左对齐； 正文：宋体、小四号、正常体，左对齐。 以上行距为单倍行距。

3.3 文档制作工具

使用何种文档制作工具，原则上没有限制，但必需考虑到文档交流的方便性问题。因此，如果在文档的交流方面，因为文档制作工具的使用差异造成工作上的不便，文档制作者本人应该设法解决。

用于交流和上交的文档登记说明上，应注明所使用的文档制作工具。

4. 文档管理规范

4.1 文档管理岗位职责

产生文档的单位包括：开发部的项目组和配置测试中心的配置测试组。

项目组的职责：

● 编写开发计划书，评审/审查通过后，向配置测试组提交，进入配置

管理。

● 编写阶段开发计划书、技术文档，经过评审/审查后，向配置测试组

提交，进入配置管理。

● 编写阶段总结报告，向配置测试组提交，进入配置管理。 配置测试组的职责：

● 编写配置测试评审计划书，评审/审查通过后，进入配置管理。 ● 编写阶段计划书、配置、测试和评审文档，经过评审/审查后，进入

配置管理。

● 收集项目组的管理文档和技术文档

● 执行阶段计划书、配置、测试和评审，经过评审/审查后，进入配置

管理。

● 编写阶段总结报告，进入配置管理。

4.2 文档的制作

任何软件开发技术文档的作者必须严格按照《软件开发技术文档管理规范》来制作。

技术文档的制作可以由作者本人完成，这就要求各开发人员学习文档的制作规范，按规范进行文档编写。

技术文档也可以由作者本人手工书写，交秘书来打字完成，但技术文档的作者必须进行校对工作。

4.2.1 文档的分类、编码与标识

参见《软件开发配置管理规程》

4.2.2 文档的作者、修改者和打字者

对此管理的目的是明确文档的来源，使整个开发的流程清晰可查。以便今后可就某个技术细节找到相应的人（作者）进行更进一步的探讨和学习。也便于对某个项目的工作任务作出合理的安排。

每本文档在形成时，在封面就须写清楚文档的第一作者及其合作者。如果文档进行了修改、改版，在版本更新说明中，还必须写清修改人。

在对文档进行登记归档时也必须如实记录作者。其中有第一作者，修改者。同时记录打印人和定稿打印的日期。

4.3 文档的收集

技术文档的收集包括2种方式。一种是作者将完成的合乎规范的技术文档主动交配置测试中心关于本项目指定的配置测试工程师进行配置管理。一种是配置测试中心关于本项目的配置测试工程师，根据项目阶段任务和阶段成果的安排，在适当的时候向相关的文档制作者收集技术文档，进行配置管理和版本控制。

4.4 文档的配置

与项目有关的管理文档和技术文档的管理最终统一归口于软件配置测试中心的配置管理组。技术文档的管理方式是按部门、部门下面的项目组、项目组的不同阶段加以配置管理和版本控制例如：

开发一部

湖南人行开发卷宗开发二部设计书类

开发三部PTM IS

公安、消防操作手册维护手册

方案类

测试类

以上只是管理的一种形式，它是根据部门来分类。另外还可以根据其它特征来分类。这些特征有时间、作者、部门、项目、文档类别等。具体采用什么样的特征可根据具体情况进行适当的分类。

在对文档进行管理时，必须对每一份正式的文档进行详细的登记。登记时的原则是：手续严密、格式清晰醒目、简化适用、登记项目完整详尽。这样在对文档进行管理时便于查找文档和检查文档的运转情况。一般采用簿式登记，以便清晰可查。

4.5 文档的控制

为保持文档和程序产品的一致性，保持各种文件之间的一致性和文件的安全性，需要对文档进行控制，具体表现在：

● 应该有文档管理员集中保管本项目现有全部文档的主文本两套，由

其负责保管

● 每一份提交给文档管理人员的文档必需具有编写人、审核人和批准

人的签字

● 两套文本的内容一致，其中一套可以出借，另一套绝对不可以出借 ● 文档的借阅和归还必需有出借和注销的手续

● 项目组种的个人文档必需和整个项目的主文档的内容和版本一致

● 一份文档如果被新文档更新，原文件必需注销

4.6 文档的修改管理

在项目开发过程中，项目组内部的任何人都可以提议对开发工作的文件成

果进行修改，但必需遵循如下的步骤：

● 提议：项目组内部任何一个人都可以填写修改建议表，提出对文档

的修改建议

● 评议：由项目负责人或项目负责人制定指定的人员对文档修改提议

进行评议，包括审查该项修改的必要性、影响范围、研究进行修改

的方法、步骤和实施计划

● 审核：由项目负责人进行审核，包括合适修改的目的和要求、核实

修改活动将带来的影响、审核修改活动计划是否可行

● 批准：由开发单位的部门负责人进行批准，主要是决断修改工作中

各项活动的先后顺序及各自完成日期，以保证整个开发工作按园丁

计划日期完成

● 实施：由项目负责人按已批准的修改活动计划，安排各项修改活动

的负责人进行修改，建立修改记录、产生新的文件以取代原有文档，

最后把文档交付文档管理员，并奋发给有关的持有者

4.7 文档的借阅和复制管理制度

技术文档的借阅包括3种情况。一种是在软件开发部门内部的技术文档借阅。一种是项目组内部的文档借阅，一种是已经配置管理于配置测试中心的技术文档的借阅。

对于部门内部的技术文档借阅，申请人必须拥有部门经理的签名许可。 对于项目组内部的技术文档借阅，申请人必须拥有项目经理或总设计师的签名许可。

对于配置测试中心特定技术文档的借阅，必须拥有主管技术副总裁或技术总监的签名许可。

4.8 文档的保密性

对于任何一种技术文档，必须按密级进行管理，技术文档的密级在制作规范中已经说明。借阅制度如下：

● 明文（General ）：可以自由借阅，只要办理一下借阅手续即可。出借的

文档要登记文档份数，文件名，借阅人，预期归还时间。如须长期使用，要保留复印件；

● 普通（Normal ）：只有本公司特定岗位的技术人员才可以使用的文档。 ● 秘密（Confidential ）：管理类计划和总结文档

● 机密（High Confidential）：管理规程、编写规范等文档。

● 绝密（Top Confidential ）：产品文档。

借出的文档要定期催还，因丢失文件、泄密造成的后果由借阅人承担。 关于技术文档的复制（拷贝和或打印）工作，必须依照上述的借阅制度进行。

5. 技术文档的质量评价

高质量的文档应当体现在以下几个方面：

● 规范性：符合公司关于相关类型的文档制作规范

● 针对性：文档编制以前应当分清读者对象。按不同的类型、不同层

次的读者，决定怎样适应他们的需要

● 精确性：文档的行文应当十分准确，不能出现多义性的描述

● 清晰性：文档编写应力求简明，如有可能，配以适当的图表，以增

强其清晰性。

● 完整性：任何一个文档都应当是完整的、独立的，应自成体系。

● 灵活性：各个不同软件项目，其规模和复杂程度有着许多实际差别，

不能一律看待