文档编写规范

文档编写 规范 编程规范下载gsp规范下载钢格栅规范下载警徽规范下载建设厅规范下载 XXX部 DOC.NO. Tech-Spec-Docu 普通 XXX部 文档编写规范 Version. 1.0 XXXX 2002-9-21 XXXXX公司 Tel: (0592)XXXXXXX Fax: (0592) XXXXXXX Email: XXXX@XXXXXX.com http://www.XXXXXX.com COMPANY CONFIDENTIAL AND PROPRIETRAY ©2001-2005 XXXXX All rights Reserved 文档编写规范 文档信息 文档名称: 文档编写规范 负责人: XXX 文档版本编号: Tech-Spec-Docu 密级： 普通 文档版本日期: 2001-9-21 起草人: 起草日期: 2001-9-21 复审人: 复审日期: 分发名单 来自From 日期 电话 / 传真 XXX 2001-9-21 1232 抄送To 行动* 截止日期 电话 / 传真 复审 复审 复审 *行动类别: 批准, 复审, 通知, 存档, 所需行动, 参加会议,其它 (请指明) 版本记录 版本编号 版本日期 修改者 说明 1.0 2001-9-21 XXX 草案 目录 51 规范说明 51.1 目的 51.2 适用范围 51.3 名词解释 51.4 正文内容 51.5 解释权限 51.6 施行日期 62 文档统一格式定义 62.1 文档页面设置 62.2 封面格式 72.3 文档版本说明格式 72.4 页眉与页尾格式 72.5 目录格式 72.6 正文格式 83 文档编写规范 83.1 需求说明书 83.1.1 引言 83.1.2 业务流程整体说明（使用业务语言） 83.1.3 特殊说明 83.1.4 原始资料 93.2 需求分析 报告 软件系统测试报告下载sgs报告如何下载关于路面塌陷情况报告535n,sgs报告怎么下载竣工报告下载 93.2.1 引言 93.2.2 任务概述 93.2.3 数据描述 103.2.4 功能需求 103.2.5 性能需求 103.2.6 运行环境描述 113.2.7 其他需求 113.3 概要设计书 113.3.1 引言 113.3.2 总体设计 113.3.3 接口设计 123.3.4 数据结构设计 123.3.5 出错处理设计 123.3.6 安全保密设计 123.4 详细设计书 123.4.1 引言 133.4.2 总体设计 133.4.3 程序描述 143.5 测试计划 143.5.1 引言 143.5.2 计划 143.5.3 测试项目说明 143.5.4 评价 153.6 测试报告 153.6.1 引言 153.6.2 测试计划执行情况 153.6.3 评价 153.7 模块开发文档 153.7.1 功能说明 163.7.2 设计说明 163.7.3 源代码清单 163.7.4 测试说明 163.7.5 复审结论 163.8 用户手册 163.8.1 引言 173.8.2 系统功能介绍 173.8.3 运行环境说明 173.8.4 运行前的准备 173.8.5 输入输出说明和操作说明 173.8.6 安全与保密 173.8.7 常见问题的处理 173.8.8 附录：安装与初始化 173.9 试运行计划 173.9.1 引言 173.9.2 开发背景介绍 173.9.3 运行环境介绍 173.9.4 软件流程及模块功能说明 173.9.5 试运行所需资料 173.9.6 特殊业务的处理方法说明 173.9.7 试运行所需的业务基础数据 173.9.8 试运行进度安排 173.10 验收报告 173.10.1 引言 173.10.2 验收内容 173.10.3 软件验收结论 1 规范说明 1.1 目的 为了本公司信息系统建设过程逐步规范化，实现信息系统的软件工程化实施，结合本公司的具体情况特编制《文档编制规范》。以便将来作为本公司信息系统建设软件工程化基础的一部分。 1.2 适用范围 本规范适用于XXXX。 1.3 名词解释 无 1.4 正文内容 在《文档编写规范》中定义了在项目开发和产品开发过程中必须生成的主要文档以及文档的格式与内容，这些文档包括：需求说明书、需求分析报告、概要设计书、详细设计书、测试计划、测试报告、用户手册、模块开发文档、试运行计划、验收报告。 1.5 解释权限 本规范由技术管理部负责解释。 1.6 施行日期 本规范自颁布之日起施行。 2 文档统一格式定义 2.1 文档页面设置 上 下 左 右 页眉距边界 页尾距边界 装订线 2.54cm 2.54cm 3.17cm 3.17cm 1.5cm 1.75 0cm 2.2 封面格式 见封面 2.3 文档版本说明格式 2.4 页眉与页脚格式 2.5 目录格式 各索引条目必须是正文的超链接：鼠标单击索引条目后进入正文。 2.6 正文格式 正文字体 正文字号 标题字体 标题字号 行间距 宋体 五号 黑体 小四 单倍或1.5倍行距 3 文档编写规范 3.1 需求说明书 3.1.1 引言 · 编写目的（阐明编写需求说明书的目的） · 项目背景（应包括：a.项目的委托单位、开发单位和主管部门；b.该软件系统与其他系统的关系。） · 名词解释（列出文档中所用到的专门术语的定义和缩写词的原文。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.立项报告；b.项目开发计划；c.文档所引用的资料、标准和规范。） 3.1.2 业务流程整体说明（使用业务语言） 业务人员首先应对业务有一个总体流程图，同时辅以文字说明。如果总的流程图的各个组成部分还可以细分的话，应继续用子流程图的形式对它的各组成部分进行说明并辅以文字说明，直到流程图的各个组成部分的业务步骤不可再分为止。例如代理录入订单，在详细描述中应包括以下内容：订单的详细信息；代理编号（长度要求，需要代理手工选择）；订单号（长度要求、需要代理手工输入）……………。 3.1.3 特殊说明 需要特殊说明的一些问题，例如本系统与现有其他软件系统的关系等。 3.1.4 原始资料 · 资料收集：应收集所有与业务需求相关的原始资料，为后续工作（如：需求分析等）做准备。 · 原有业务流程概述：对原有业务流程进行说明（采取流程图方式） · 原始单据、原始报表等：以列表的方式列出原始资料的名称，而且要与原有业务流程概述的内容相对照，并将实际的原始资料附在业务分析书的后面。 原始资料名称 对应于原有业务流程概述的哪一部分内容 3.2 需求分析报告 3.2.1 引言 · 编写目的（阐明编写需求分析报告的目的） · 项目背景（应包括：a.项目的委托单位、开发单位和主管部门；b.该软件系统与其他系统的关系。） · 名词解释（列出文档中所用到的专门术语的定义和缩写词的原文。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.立项报告；b.项目开发计划；c.文档所引用的资料、标准和规范。） 3.2.2 任务概述 · 目标 叙述该项软件开发的意图、应用目标、作用范围以及该软件的背景资料。解释被开发软件与其他有关软件之间的关系。如果本软件是一个独立的软件，而且全部内容自含，则说明这一点。如果定义的产品是一个更大系统的一个组成部分，则应说明本产品与该系统中其他各组成部分之间的关系。 · 假定与约束 列出本软件开发工作的假定与约束，例如经费限制、开发期限等等。 3.2.3 数据描述 数据分为静态数据和动态数据。所谓静态数据，指在运行过程中主要作为参考的数据，它们在很长一段时间内不会变化，一般也不会随着运行而改变，所谓动态数据，包括所有在运行中要发生变化的数据，以及在运行中要输入、输出的数据。 · 静态数据（系统运行前已有的数据） 列出所有作为控制或参考用的静态数据，并给出名称。 · 动态数据（系统运行过程中需要的输入数据以及系统运行过程中产生的输出数据） 列出所有动态数据，并给出名称。 3.2.4 功能需求 · 流程图 画出系统的整体流程图。 · 功能划分 对于流程图中的各个功能用树状结构自顶向下进行细化。并对最底层的功能进行编码，给出功能标识符。 · 功能描述 对最底层的功能所要完成的功能进行详细描述，填入下表中： 功能名称 功能标识符 功能详细描述 · 数据与功能的对应关系 用一张矩阵图说明功能描述中的各个功能与数据描述中的静态数据、动态数据之间的对应关系，例如： 功能标识符 输入 输出 功能标识符1 静态数据名称 动态数据名称（例如用户在运行过程中需要用键盘输入数据） 动态数据名称（例如在运行过程中需要写日志或输出一个报表） 功能标识符2 动态数据名称 动态数据名称 3.2.5 性能需求 · 时间要求 例如响应时间、更新处理时间、数据转换和传送时间等等。 · 适应性（在操作方式、运行环境、与其他软件的接口等发生变化时，所具有的适应能力。） 3.2.6 运行环境描述 · 硬件设备 · 支持软件（操作系统、数据库、其他软件系统如：Lotus Notes等） · 接口（硬件接口、软件接口） · 控制（说明控制该软件的运行的方法） · 用户界面（反映业务流程的用户界面） 3.2.7 其他需求 · 如可用性、安全保密、可维护性、可跨平台性等。（分高、中、低定性详细描述） 3.3 概要设计书 3.3.1 引言 · 编写目的（阐明编写概要设计书的目的，指明读者对象。） · 项目背景（应包括：a.项目的委托单位、开发单位和主管部门；b.该软件系统与其他系统的关系。） · 定义（列出本文档中所用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：立项报告；项目开发计划；需求分析报告；文档所用的资料、采用的标准或规范。） 3.3.2 总体设计 · 需求概述 · 运行环境 简要的说明对本系统的运行环境（包括硬件环境和支持环境）的规定 · 处理流程 针对《需求分析报告》中功能需求的功能描述部分，用图的形式表示出完成该功能的模块的处理流程。并注明各个模块之间的接口参数。 · 总体结构 针对《需求分析报告》中功能需求的功能描述部分，用树状图的形式，自顶向下的表示出完成该功能的所有模块的结构图。 · 功能分配（表明各项功能与程序结构的关系。） 用一张矩阵图说明各项功能需求的实现与各模块的分配关系。 模块1 模块2 . . . . . . 功能需求1 . . . . . . 功能需求n 3.3.3 接口设计 · 用户接口 说明向用户提供的命令和它们的语法结构，以及软件的回答信息 · 外部接口 说明本系统与外界的所有接口，包括软件与硬件之间的接口，本软件与其他软件之 间的接口关系。 · 内部接口 针对在总体设计部分的总体结构中列出的模块树状结构图，对树状图中位于同一层的各个模块之间的接口进行详细说明。 3.3.4 数据结构设计 · 逻辑结构设计（数据字典） · 物理结构设计 数据字典的存储要求、访问方法、存取的物理关系（包括索引、设备等等） · 数据结构与程序的关系 用一张矩阵图说明各个数据库表与各模块的对应关系。 模块1 模块2 . . . . . . 数据库表1 . . . . . . 数据库表n 3.3.5 出错处理设计 · 出错输出信息 用表的形式说明可能出现的出错或故障情况出现时，系统输出信息的形式，含义以及处理方法。 · 出错处理对策 说明故障出现后可能采用的补救措施，包括： 后备技术：当原始数据丢失时起用数据副本的技术 性能降级：当系统崩溃时，暂时采用人工处理的办法 恢复及再启动：是软件从故障点恢复执行或使软件从头开始运行的方法 3.3.6 安全保密设计 指从系统安全保密角度考虑，在程序设计和数据库设计中作出的一些安排。例如为了保证传输数据的完整性与保密性，需要在传递数据前对数据进行加密。 系统维护设计 说明为了系统维护的方便而在程序设计中作出的安排，包括在程序中专门安排用于系统的检查与维护的检测点和专用模块。 3.4 详细设计书 3.4.1 引言 · 编写目的（阐明编写详细设计书的目的，指明读者对象。） · 项目背景（应包括：a.项目的委托单位、开发单位和主管部门；b.该软件系统与其他系统的关系。） · 定义（列出文档中所用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：项目的计划任务书、 合同 劳动合同范本免费下载装修合同范本免费下载租赁合同免费下载房屋买卖合同下载劳务合同范本下载 或批文；立项报告.；项目开发计划；需求分析报告；概要设计书；测试计划；文档中所引用的其他资料、软件开发标准或规范。） 3.4.2 总体设计 · 需求概述 · 软件结构（如给出软件系统的结构图。） 对《概要设计书》中的总体结构部分的各个模块，用列表的方式给出该模块包含的程序的名称、标识符、功能列表。 3.4.3 程序描述 （逐个程序给出以下的说明：） · 功能 说明该程序应具有的功能。 · 性能 说明对该程序的性能要求，包括精度、灵活性、时间特性等要求。 · 输入项目 给出每一个输入项目的特性，包括名称、标识符、数据的类型和格式、数据值的有效范围、输入的方式、输入媒体等等。 · 输出项目 给出每一个输出项目的特性，包括名称、标识符、数据的类型和格式、数据值的有效范围、输出的形式、输出媒体等等。 · 算法 本程序所选用的算法，具体的计算公式和计算步骤。 · 流程逻辑 用流程图的形式辅以必要的说明来表示本程序的逻辑流程。 · 接口 说明本程序所隶属的上一层模块及隶属于本程序的下一层模块、子程序，说明参数赋值和调用方式，说明与本程序直接关联的数据库。 · 限制条件 · 测试要点（给出测试模块的主要测试要求。） · 尚未解决的问题 3.5 测试计划 3.5.1 引言 · 编写目的（阐明编写测试计划的目的并指明读者对象。） · 项目背景 · 本测试计划所从属的软件系统的名称； · 项目的委托单位、开发单位和主管部门； · 该软件系统与其他系统的关系。 · 定义（列出测试计划中所用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.项目的计划书、合同或批文；b.项目开发计划；c.需求分析报告；d.概要设计书；e.详细设计书；f.用户手册；g.本测试计划中引用的其他资料、采用的软件开发标准或规范。） 3.5.2 计划 · 测试 方案 气瓶 现场处置方案 .pdf气瓶 现场处置方案 .doc见习基地管理方案.doc关于群访事件的化解方案建筑工地扬尘治理专项方案下载 （说明确定测试方法和选取测试用例的原则如：用户界面测试、功能流程测试、性能测试。） · 测试项目（列出组装测试和确认测试中每一项测试的内容、名称、目的和进度。） · 测试准备 · 测试机构及人员（测试机构名称、负责人和职责。） 3.5.3 测试项目说明 （按顺序逐个对测试项目做出说明：） · 测试项目名称及测试内容 · 测试用例 1. 输入（输入的数据和输入命令。） 2. 输出（预期的输出数据。） 3. 步骤及操作 · 进度 · 条件（给出项测试对资源的特殊要求，如设备、软件、人员等。） · 测试资料（说明项测试所需的资料。） 3.5.4 评价 · 范围（说明所完成的各项测试说明问题范围及其局限性。） · 准则（说明评价测试结果的准则。） 3.6 测试报告 3.6.1 引言 · 编写目的（阐明编写测试报告的目的并指明读者对象。） · 项目背景 · 本测试计划所从属的软件系统的名称； · 项目的委托单位、开发单位和主管部门； · 该软件系统与其他系统的关系。 · 定义（列出测试报告中用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.项目的计划任务书、合同或批文；b.项目开发计划；c.需求分析报告；d.概要设计书；e.详细设计书；f.用户手册；g.测试计划；h.所引用的其他资料、采用的软件工程标准或 软件工程规范。） 3.6.2 测试计划执行情况 · 测试项目（用 表格 关于规范使用各类表格的通知入职表格免费下载关于主播时间做一个表格详细英语字母大小写表格下载简历表格模板下载 的形式列出每一测试项目的名称、内容和目的。） · 测试机构和人员（给出测试机构名称、负责人和参与测试人员名单。） · 测试结果（按顺序给出每一测试项目的：a.实测结果数据；c.该项测试表明的事实；d.该项测试发现的问题。） 软件需求测试结论 · 顺序给出每一项需求测试的结论。包括：a.证实的软件能力；b.局限性（哪项需求未得到充分测试的情况及原因。） 3.6.3 评价 · 软件能力（经过测试所表明的软件能力。） · 建议（提出为弥补上述缺陷的建议。） · 缺陷和限制（说明测试所揭露的软件缺陷和不足，以及可能给软件运行带来的影响。） · 测试结论（说明能否通过。） 3.7 模块开发文档 项目名称 模块名称 作 者 起始日期 年 月 日 完成日期 年 月 日 3.7.1 功能说明 说明本模块或本组模块的功能，主要是输入、要求的处理、输出，并附上《需求分析报告》中对这些功能的说明部分。 3.7.2 设计说明 说明本模块的设计考虑，包括： 1. 在《概要设计书》中对本模块（或本组模块）设计考虑的叙述，包括本模块在软件系统中所处的层次，它同其他模块的接口。 2. 在《详细设计书》中对本模块（或本组模块）的设计考虑，包括本模块的算法、处理流程、出错信息等等 3. 在编写源代码时实际使用的设计考虑 3.7.3 源代码清单 给出已通过全部测试的源代码清单。 3.7.4 测试说明 说明该模块自测试的目的、输入、预期的输出和实际的输出。 3.7.5 复审结论 把实际测试的结果，同《需求分析报告》、《概要设计书》、《详细设计书》中规定的要求进行比较并给出结论。 3.8 用户手册 3.8.1 引言 · 编写目的（阐明编写用户手册的目的并指明读者对象。） · 项目背景 · 本用户手册所从属的软件系统的名称； · 项目的委托单位、开发单位和主管部门； · 该软件系统与其他系统的关系。 · 定义（列出用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.项目的计划任务书、合同或批文；b.项目开发计划；c.需求分析报告；d.概要设计书；e.详细设计书；f.测试计划；g.所引用的其他资料、采用的软件工程标准或软件工程规范。） 3.8.2 系统功能介绍 按照软件使用者的一般工作分工说明软件所具有的功能、这些功能帮助使用者解决实际工作中的哪些问题、使用软件后的优点。 3.8.3 运行环境说明 简单说明运行本软件所要求的： · 硬件设备环境，例如使用什么型号的计算机、配备多少内存及硬盘等； · 系统软件的环境，例如WINDOWS、SQL*NET等； · 应用软件环境，例如运行本软件时需要在系统中有哪些其他子系统的支持等。 必要时可以说明软件运行的基本环境和最佳环境。 3.8.4 运行前的准备 说明这个软件在运行前用户应该作的准备工作，如：代码的编制、数据的准备、工作流程的调整等等。在这里应该列出所需要做的准备工作清单，以告诉用户在使用前应做好的准备工作。有些系统初始化的工作，特别是需要系统维护人员操作的安装和初始化工作操作方法可在后面附录的安装与初始化中描述，在这里不必详细说明。 3.8.5 输入输出说明和操作说明 这一部分是用户手册的核心，这部分内容应该按照工作的流程顺序来编写。 对于每个相对独立运行的子系统或程序模块，应说明软件的进入和退出方法。（在WINDOWS环境下的软件只需说明快捷方式启动软件的方法即可，通常情况下不必再说明用命令启动软件的方法。） 在编写操作说明时为了用户使用的方便，应该针对每一个工作流程编写相应的软件操作步骤和方法，其内容应该包括： · 功能简介。 · 工作流程中相应软件模块的进入与退出方法。 · 以醒目的方式列出常规工作时操作步骤，详细说明每个步骤中的屏幕和使用方法 · 这一部分应该尽量让软件的使用操作人员对整个操作过程有一个明确的概念，在文件编排上应该把使用者的注意力集中在使用软件解决他工作中的问题上。 · 对向计算机输入的数据和计算机输出的内容给予适当的说明。 在语言上应该使用易于用户理解的词汇而尽量不要用计算机专业术语。 3.8.6 安全与保密 说明软件对保密管理的要求及违反保密规定后可能造成的后果。在一些子系统中，保密字乱用后，可能造成个人工作量统计错误等等。 3.8.7 常见问题的处理 根据需要说明在使用中可能遇到的问题及其解决方法。这些问题往往是由于在使用过程中的错误操作造成的。对于一些能够预见的，经常可能遇到的问题应该在用户手册中提供解决的方法，这样能够减少很多为用户提供使用咨询的工作量。 3.8.8 附录：安装与初始化 · 安装 列出软件安装的步骤，说明安装过程中的每一步操作方法。这一部分的内容应该让初次接触这个系统的使用者依照手册中所列的步骤和操作方法顺利地将软件安装上。 · 初始化 列出软件正式运行前所需要进行初始化工作的清单和初始化操作的步骤。对于初始化中的每个步骤应给予适当的说明，使进行初始化工作的人能够充分理解初始化中每一步骤的实际作用，以便于合理地配置应用系统，充分发挥系统的作用 3.9 试运行计划 3.9.1 引言 · 编写目的（阐明试运行计划的目的并指明读者对象。） · 项目背景 · 软件系统的名称； · 项目的委托单位、开发单位和主管部门； · 该软件系统与其他系统的关系。 · 定义（列出文档中用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.项目的计划书、合同或批文；b.项目开发计划；c.需求分析报告；d.概要设计书；e.详细设计书；f.用户手册；g.测试计划；h.所引用的其他资料、采用的软件工程标准或软件工程规范。） 3.9.2 开发背景介绍 包括业务需求提出的起因、项目负责人、开发人员（开发商）、测试负责人、业务系统涉及部门 3.9.3 运行环境介绍 硬件设备、网络环境、软件平台等等 3.9.4 软件流程及模块功能说明 提供一份图表或流程图，并逐项说明软件系统各个模块的功能、输入和输出的业务数据的提纲。 3.9.5 试运行所需资料 包括用户使用手册、规范的业务操作流程、业务数据、问题记录表等。 3.9.6 特殊业务的处理方法说明 3.9.7 试运行所需的业务基础数据 3.9.8 试运行进度安排 序号 业务模块名称 试运行时间段 试运行人员 3.10 验收报告 3.10.1 引言 · 编写目的（阐明编写验收报告的目的并指明读者对象。） · 项目背景 · 软件系统的名称； · 项目的委托单位、开发单位和主管部门； · 该软件系统与其他系统的关系。 · 定义（列出验收报告中用到的专门术语的定义和缩写词的原意。） · 参考资料（列出有关资料的作者、标题、编号、发表日期、出版单位或资料来源，可包括：a.项目的计划书、合同或批文；b.项目开发计划；c.需求分析报告；d.概要设计书；e.详细设计书；f.用户手册；g.测试计划；h. 所引用的其他资料、采用的软件工程标准或软件工程规范。） 3.10.2 验收内容 验收的基本内容应基于项目开发合同。 · 文档（列出每一阶段提交的文档的名称、内容和评价。） · 程序（对于每一子功能的功能测试情况，界面与操作评价，此部分应基于《需求分析报告》和《概要设计书》） 3.10.3 软件验收结论 · 是否通过验收 · 评价 XXX公司 第6页/共19页 _1040644796.vsd _1040625918.doc 子流程图2中 组成部分2 详细描述 子流程图2中 组成部分1 详细描述 子流程图2的文字说明 子流程图2 子流程图1中 组成部分2 详细描述 子流程图1中 组成部分1 详细描述 子流程图1的文字说明 子流程图1 总体流程图的文字说明 总体流程图