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

ISO9001 质量体系作业文件质量体系作业文件 名名 称称 软件开发技术文档管理规范软件开发技术文档管理规范 编编 号号 版号版号 拟拟 制制 日期日期 审审 核核 日期日期 批批 准准 日期日期 生效日期生效日期 受控状态受控状态 发文号发文号 会签部门会签人 日期会签部门会签人 日期 软件开发技术文档管理规范软件开发技术文档管理规范 第第 1 页页 共共 13 页页 目录目录 1 前言前言 1 1 1目的 1 1 2术语 1 1 3参考文献 1 1 4版本说明和修改历史 1 2 软件文档软件文档 1 2 1文档的定义及作用 1 2 2软件文档的分类 2 2 3软件文档的制作与软件生存周期之间的关系 3 2 4文档的使用者 3 3 文档编制格式规范文档编制格式规范 4 3 1文档编码规则 4 3 2文档组成格式 4 3 2 1封面 5 3 2 2目录 6 3 2 3版本更新说明 6 3 2 4文件内容 6 3 2 5正文格式 7 3 3文档制作工具 7 4 文档管理规范文档管理规范 7 4 1文档管理岗位职责 7 4 2文档的制作 8 4 2 1文档的分类 编码与标识 8 4 2 2文档的作者 修改者和打字者 8 4 3文档的收集 8 4 4文档的配置 9 4 5文档的控制 9 4 6文档的修改管理 9 4 7文档的借阅和复制管理制度 10 4 8文档的保密性 10 5 技术文档的质量评价技术文档的质量评价 11 软件开发技术文档管理规范软件开发技术文档管理规范 第第 1 页页 共共 13 页页 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 页页 共共 13 页页 2 软件文档软件文档 2 1 文档的定义及作用文档的定义及作用 文档 document 是指某种数据媒体和其中所记录的数据 它具有永久性 并可以由人或机器阅读 通常仅用于描述人工可读的东西 正确地制作和使用软件文档 可以获得如下的便利 提高软件开发过程的能见度 提高开发效率 作为开发人员在一定阶段的工作成果和结束标志 记录开发过程中的有关信息 便于协调以后的软件 开发 使用和 维护 便于潜在用户了解软件的功能 性能等各项指标 为他们选购符合 自己需要的软件提供依据 2 2 软件文档的分类软件文档的分类 对于软件文档的分类有多种方法 从形式上分为两类 开发过程中可以填写的各种图表 可称之为工作表格 应编制的技术资料或技术管理资料 可称之为文档或文件 按照软件文档的产生和使用范围可以分为三类 开发文档 软件开发过程中 作为软件开发人员前一阶段工作成果 的体现和后一阶段工作依据的文档 包括可行性研究 项目开发计 划 需求说明 数据说明 概要设计和详细设计 管理文档 软件开发过程中 由软件开发人员制定的需提交管理人 员的一些工作计划和工作报告 包括项目开发计划 测试计划 测 试报告 开发进度月报及项目开发总结 用户文档 软件开发人员为用户准备的有关该软件使用 操作 维 护的资料 包括用户手册 操作手册 维护修改建议 需求说明 按照计算机软件产品开发文件编制指南的国家标准 GB8567 88 的要求 在一项计算机软件的开发过程中 一般地说 应该产生 14 种文件 可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 概要设计说明书 详细设计说明书 数据库设计说明书 用户手册 操作手册 软件开发技术文档管理规范软件开发技术文档管理规范 第第 3 页页 共共 13 页页 模块开发卷宗 测试计划 测试分析报告 开发进度月报 项目开发总结报告 2 3 软件文档的制作与软件生存周期之间的关系软件文档的制作与软件生存周期之间的关系 一般而言 计算机软件生存周期可以分为六个阶段 可行性与计划研究阶段 需求分析阶段 设计阶段 实现阶段 测试阶段 运行与维护阶段 在软件开发的不同阶段 产生的软件文档不同 具体对应关系如下表所示 阶段 文档 可行性研究与计划 阶段 需求分 析阶段 设计 阶段 实现 阶段 测试 阶段 运行与维 护阶段 可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明 书 模块开发卷宗 用户手册 操作手册 测试分析报告 开发进度月报 项目开发总结 2 4 文档的使用者文档的使用者 对于软件文档的使用人员而言 与其所承担的工作有关 具体情况如下所示 管理人员 可行性研究报告 项目开发计划书 软件开发技术文档管理规范软件开发技术文档管理规范 第第 4 页页 共共 13 页页 模块开发卷宗 开发进度月报 项目开发总结报告 开发人员 可行性研究报告 项目开发计划书 需求分析说明书 概要设计说明书 详细设计说明书 数据库设计说明书 测试计划 测试分析报告 维护人员 设计说明书 测试分析报告 模块开发卷宗 最终用户 系统安装手册 用户手册 系统维护手册 系统功能说明书 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 文件内容等组成 如图所示 软件开发技术文档管理规范软件开发技术文档管理规范 第第 5 页页 共共 13 页页 件 件 件 件 件 件 件 件 件 件 件件 件件 件件 件 件 件 件 目 录 图图1 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 明文 可以在社会上广为流传 例 NormalNormal 软件开发技术文档管理规范软件开发技术文档管理规范 第第 6 页页 共共 13 页页 5 版本号版本号 关键词为 Version 用 Arial 字体 大小为小四号 例 Version V1 0 0 6 完成日期完成日期 用Arial 字体 大小为小四号 例 1994 11 14 7 作者作者 Written By 用 Arial 字体 大小为小四号 加粗 例 WrittenWritten ByBy POWERISEPOWERISE 8 公司公司LOGO LOGO 用 USABLack 字体 大小为四号 加粗 例 POWERISEPOWERISE 9 公司名称及版权生效年份公司名称及版权生效年份 关键词为 创智软件园有限公司 Powerise Software Inc 版权生效年限 关键词为 C 公历年号 中文字体 黑体 四号 加粗 例 创智软件园有限公司 C 1994 1999 注 此处填写产品已经经过的年份 如注 此处填写产品已经经过的年份 如PowerLCMS copyrights C 1996 1998 PowerLCMS copyrights C 1996 1998 英文字体 Arial 四号 加粗 例 PowerisePowerise Software Inc C 1994 1995Software Inc C 1994 1995 10 版权申明版权申明 字体为 Arial 小四 加粗 例 AllAll RightRight ReservedReserved 各项安排如下图 样板范例可参见本文档的封面 1 2 4 3 5 6 7 8 9 10 3 2 2 目录目录 可采用手工编制或使用文档编制 Microsoft Word 的自动生成目录的功能 产生文档目录 软件开发技术文档管理规范软件开发技术文档管理规范 第第 7 页页 共共 13 页页 3 2 3 版本更新说明版本更新说明 关键词为 Revision 内容划分为 日期 Date 理由 Reason 更新者 Revisor 首版可省略该节 3 2 4 文件内容文件内容 文件内容每一页必须包含下列三项 缺一不可 页首 在页首中部自动填入 标题1 的名称 页脚 在页脚左部填入创智标徽POWERISEPOWERISE 右部填入页号 正文 如下图所示 具体设置可复制本文作模块 标题 Powerise 创智 创智标徽image 第X页 3 2 5 正文格式正文格式 标题一 宋体 小三 粗体 左对齐 标题二 黑体 四号 粗体 左对齐 标题三 宋体 小四号 粗体 左对齐 标题四 黑体 小四号 正常体 左对齐 标题五 黑体 五号 粗体 左对齐 正文 宋体 小四号 正常体 左对齐 以上行距为单倍行距 3 3 文档制作工具文档制作工具 使用何种文档制作工具 原则上没有限制 但必需考虑到文档交流的方便 性问题 因此 如果在文档的交流方面 因为文档制作工具的使用差异造成工 作上的不便 文档制作者本人应该设法解决 用于交流和上交的文档登记说明上 应注明所使用的文档制作工具 软件开发技术文档管理规范软件开发技术文档管理规范 第第 8 页页 共共 13 页页 4 文档管理文档管理规范规范 4 1 文档管理岗位职责文档管理岗位职责 产生文档的单位包括 开发部的项目组和配置测试中心的配置测试组 项目组的职责 编写开发计划书 评审 审查通过后 向配置测试组提交 进入配 置管理 编写阶段开发计划书 技术文档 经过评审 审查后 向配置测试 组提交 进入配置管理 编写阶段总结报告 向配置测试组提交 进入配置管理 配置测试组的职责 编写配置测试评审计划书 评审 审查通过后 进入配置管理 编写阶段计划书 配置 测试和评审文档 经过评审 审查后 进 入配置管理 收集项目组的管理文档和技术文档 执行阶段计划书 配置 测试和评审 经过评审 审查后 进入配 置管理 编写阶段总结报告 进入配置管理 4 2 文档的制作文档的制作 任何软件开发技术文档的作者必须严格按照 软件开发技术文档管理规范 来制作 技术文档的制作可以由作者本人完成 这就要求各开发人员学习文档的制 作规范 按规范进行文档编写 技术文档也可以由作者本人手工书写 交秘书来打字完成 但技术文档的 作者必须进行校对工作 4 2 1 文档的分类 编码与标识文档的分类 编码与标识 参见 软件开发配置管理规程 4 2 2 文档的作者 修改者和文档的作者 修改者和打字者打字者 对此管理的目的是明确文档的来源 使整个开发的流程清晰可查 以便今 后可就某个技术细节找到相应的人 作者 进行更进一步的探讨和学习 也便 于对某个项目的工作任务作出合理的安排 每本文档在形成时 在封面就须写清楚文档的第一作者及其合作者 如果 文档进行了修改 改版 在版本更新说明中 还必须写清修改人 软件开发技术文档管理规范软件开发技术文档管理规范 第第 9 页页 共共 13 页页 在对文档进行登记归档时也必须如实记录作者 其中有第一作者 修改者 同时记录打印人和定稿打印的日期 4 3 文档的收集文档的收集 技术文档的收集包括 2 种方式 一种是作者将完成的合乎规范的技术文档 主动交配置测试中心关于本项目指定的配置测试工程师进行配置管理 一种是 配置测试中心关于本项目的配置测试工程师 根据项目阶段任务和阶段成果的 安排 在适当的时候向相关的文档制作者收集技术文档 进行配置管理和版本 控制 4 4 文档的配置文档的配置 与项目有关的管理文档和技术文档的管理最终统一归口于软件配置测试中 心的配置管理组 技术文档的管理方式是按部门 部门下面的项目组 项目组 的不同阶段加以配置管理和版本控制例如 开发一部 开发二部 开发三部PTMIS 湖南人行 公安 消防 设计书类 操作手册 维护手册 方案类 测试类 开发卷宗 以上只是管理的一种形式 它是根据部门来分类 另外还可以根据其它特 征来分类 这些特征有时间 作者 部门 项目 文档类别等 具体采用什么 样的特征可根据具体情况进行适当的分类 在对文档进行管理时 必须对每一份正式的文档进行详细的登记 登记时 的原则是 手续严密 格式清晰醒目 简化适用 登记项目完整详尽 这样在 对文档进行管理时便于查找文档和检查文档的运转情况 一般采用簿式登记 以便清晰可查 4 5 文档的控制文档的控制 为保持文档和程序产品的一致性 保持各种文件之间的一致性和文件的安 全性 需要对文档进行控制 具体表现在 应该有文档管理员集中保管本项目现有全部文档的主文本两套 由 软件开发技术文档管理规范软件开发技术文档管理规范 第第 10 页页 共共 13 页页 其负责保管 每一份提交给文档管理人员的文档必需具有编写人 审核人和批准 人的签字 两套文本的内容一致 其中一套可以出借 另一套绝对不可以出借 文档的借阅和归还必需有出借和注销的手续 项目组种的个人文档必需和整个项目的主文档的内容和版本一致 一份文档如果被新文档更新 原文件必需注销 4 6 文档的修改管理文档的修改管理 在项目开发过程中 项目组内部的任何人都可以提议对开发工作的文件成 果进行修改 但必需遵循如下的步骤 提议 项目组内部任何一个人都可以填写修改建议表 提出对文档 的修改建议 评议 由项目负责人或项目负责人制定指定的人员对文档修改提议 进行评议 包括审查该项修改的必要性 影响范围 研究进行修改 的方法 步骤和实施计划 审核 由项目负责人进行审核 包括合适修改的目的和要求 核实 修改活动将带来的影响 审核修改活动计划是否可行 批准 由开发单位的部门负责人进行批准 主要是决断修改工作中 各项活动的先后顺序及各自完成日期 以保证整个开发工作按园丁 计划日期完成 实施 由项目负责人按已批准的修改活动计划 安排各项修改活动 的负责人进行修改 建立修改记录 产生新的文件以取代原有文档 最后把文档交付文档管理员 并奋发给有关的持有者 4 7 文档的借阅和复制管理制度文档的借阅和复制管理制度 技术文档的借阅包括 3 种情况 一种是在软件开发部门内部的技术文档借 阅