文档编写规范.doc

文档编写规范 XXX部DOC.NO. Tech-Spec-Docu普通XXX部文档编写规范Version. 1.0XXXX2002-9-21XXXXX公司Tel: (0592)XXXXXXXFax: (0592) XXXXXXXEmail: XXXXXXXXXX.comhttp:/www.XXXXXX.comCOMPANY CONFIDENTIAL AND PROPRIETRAY2001-2005 XXXXX All rights ReservedXXX公司 第20页/共20页文档编写规范文档信息 文档名称:文档编写规范负责人:XXX 文档版本编号:Tech-Spec-Docu密级：普通 文档版本日期:2001-9-21起草人:起草日期:2001-9-21复审人: 复审日期:分发名单来自From日期电话 / 传真XXX2001-9-211232抄送To 行动*截止日期电话 / 传真复审复审复审*行动类别: 批准, 复审, 通知, 存档, 所需行动, 参加会议,其它 (请指明)版本记录版本编号版本日期修改者说明1.02001-9-21XXX草案目录1规范说明51.1目的51.2适用范围51.3名词解释51.4正文内容51.5解释权限51.6施行日期52文档统一格式定义62.1文档页面设置62.2封面格式62.3文档版本说明格式72.4页眉与页尾格式72.5目录格式72.6正文格式73文档编写规范83.1需求说明书83.1.1引言83.1.2业务流程整体说明（使用业务语言）83.1.3特殊说明83.1.4原始资料83.2需求分析报告93.2.1引言93.2.2任务概述93.2.3数据描述93.2.4功能需求103.2.5性能需求103.2.6运行环境描述103.2.7其他需求113.3概要设计书113.3.1引言113.3.2总体设计113.3.3接口设计113.3.4数据结构设计123.3.5出错处理设计123.3.6安全保密设计123.4详细设计书123.4.1引言123.4.2总体设计133.4.3程序描述133.5测试计划143.5.1引言143.5.2计划143.5.3测试项目说明143.5.4评价143.6测试报告153.6.1引言153.6.2测试计划执行情况153.6.3评价153.7模块开发文档153.7.1功能说明153.7.2设计说明163.7.3源代码清单163.7.4测试说明163.7.5复审结论163.8用户手册163.8.1引言163.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软件验收结论171 规范说明1.1 目的为了本公司信息系统建设过程逐步规范化，实现信息系统的软件工程化实施，结合本公司的具体情况特编制文档编制规范。以便将来作为本公司信息系统建设软件工程化基础的一部分。1.2 适用范围本规范适用于XXXX。1.3 名词解释无1.4 正文内容在文档编写规范中定义了在项目开发和产品开发过程中必须生成的主要文档以及文档的格式与内容，这些文档包括：需求说明书、需求分析报告、概要设计书、详细设计书、测试计划、测试报告、用户手册、模块开发文档、试运行计划、验收报告。1.5 解释权限本规范由技术管理部负责解释。1.6 施行日期本规范自颁布之日起施行。2 文档统一格式定义2.1 文档页面设置上下左右页眉距边界页尾距边界装订线2.54cm2.54cm3.17cm3.17cm1.5cm1.750cm2.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. . . . . .数据库表n3.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 计划 测试方案（说明确定测试方法和选取测试用例的原则如：用户界面测试、功能流程测试、性能测试。） 测试项目（列出组装测试和确认测试中每一项测试的内容、名称、目的和进度。） 测试准备 测试机构及人员（测试机构名称、负责人和职责。）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 附录：安装与初始化 安装列出软件安装的步骤，说明安装过程中的每一步操作方法。这一部分的内容应该让初次接触这个系统的使用者依照手册中所列的步骤和操作方法顺利地将软件安装上。 初始化列出软件正式运行前所需要进行初始化工作的清单和初始化操作的步骤。对于初始化中的每个步骤应给予适当的说明，使进行初始化工作的人能够充分理解初始化中每一步骤的实际作用，以便于合理地配置应用