软件文档.docx

1、软件文档软件文档编写指导陈正铭软件文档可以分为开发文档和产品文档两大类：（1）开发文档包括：功能要求、需求分析、技术分析、系统分析与设计、数据库文档、功能函数文档、界面文档、编译手册等。 （2）产品文档包括：产品简介、产品演示、疑问解答、功能介绍、技术白皮书、安装手册、使用手册、维护手册等。 一、开发文档 1. 功能要求-来源于客户要求和市场调查，是软件开发中最早期的一个环节。客户提出一个模糊的功能概念，或者要求解决一个实际问题，或者参照同类软件的一个功能。有软件经验的客户还会提供比较详细的技术规范书，把他们的要求全部列表书写在文档中，必要时加以图表解说。这份文档是需求分析的基础。 2.需求分

2、析-包括产品概述、主要概念、操作流程、功能列表和解说、注意事项、系统环境等。以功能要求为基础，进行详细的功能分析(包括客户提出的要求和根据开发经验建议的功能)，列出本产品是什么，有什么特殊的概念，包括那些功能分类，需要具备什么功能，该功能的操作如何，实现的时候该注意什么细节，客户有什么要求，系统运行环境的要求等。这里的功能描述跟以后的使用手册是一致的。 3. 技术分析-包括技术选型、技术比较、开发人员、关键技术问题的解决、技术风险、技术升级方向、技术方案评价，竞争对手技术分析等。以需求分析为基础，进行详细的技术分析(产品的性能和实现方法)，列出本项目需要使用什么技术方案，为什么，有哪些技术问题

3、要解决 ，估计开发期间会碰到什么困难，技术方案以后如何升级，对本项目的技术有什么评价等。 4. 系统分析与设计-包括功能实现、模块组成、功能流程图、函数接口、数据字典、软件开发需要考虑的各种问题等。以需求分析为基础，进行详细的系统分析(产品的开发和实现方法)，估计开发期间需要把什么问题说明白，程序员根据系统分析，开始在项目主管的带领下进行编码。 5. 数据库文档-包括数据库名称、表名、字段名、字段类型、字段说明、备注、字段数值计算公式等。以系统分析为基础，进行详细的数据库设计。必要时可以用图表解说，特别是关系数据库。 6. 功能函数文档-包括变量名、变量初植、功能，函数名，参数，如何调用、备注

4、、注意事项等。以系统分析为基础，进行详细的说明，列出哪个功能涉及多少个函数，以便以后程序员修改、接手和扩展。 7. 界面文档-包括软件外观、界面素材、编辑工具、文件名、菜单、按钮和其它界面部件的要求，这里与软件完成后的运行界面是一致的。 8. 编译手册-包括服务器编译环境、操作系统、编译工具、GNU的C+编译器版本信息、目录说明、程序生成、源程序文件列表、Makefile配置及其相关程序的对应关系列表。客户端的编译过程、编译结果、编译示例、编译环境、操作系统、编译工具、源文件列表和制作安装程序的过程。 二、产品文档 1. 产品简介-包括公司背景、产品概念、适用范围、产品功能、功能特点、运行要求

5、和公司联系地址。 2. 产品演示-包括公司简介、产品背景、产品描述、产品特点、产品作用、适用范围、使用分析、功能模块、解决问题、合作伙伴、成功案例等。一般用Power point或者VCD录制软件实现。 3. 疑问解答-列出用户关心的问题和处理方法。用于解答软件的操作功能和解决用户的疑难问题。 4. 功能介绍-以需求分析为书写基础，包括软件介绍、软件结构、功能列表、功能描述和公司联系地址。 5. 技术白皮书-以技术分析为书写基础，包括功能实现、技术选型、关键技术问题的解决、技术方案特点、技术升级方向等。 6.安装手册-包括系统环境、运行平台、产品安装过程、初始环境设置、安装记录等。 7. 使用

6、手册-包括产品简介、功能列表、功能描述和解释、功能操作、客户服务和联系方式等。 8. 维护手册-包括产品简介、系统须知、初始环境设置、系统配置、数据管理和备份、技术问题解答和联系方式等。 由于软件需要完成的全部软件文档较多，但对于小型系统开发可根据实际情况只编制需求分析说明书、数据库设计说明书、概要设计说明书、详细设计说明书、用户手册。开发文档中的功能要求、需求分析、技术分析可合并到需求分析说明书中；系统分析与设计即概要设计说明书；功能函数文档、界面文档、编译手册可合并到详细设计说明书中；产品文档中的产品简介、产品演示、疑问解答、功能介绍、技术白皮书、安装手册、使用手册、维护手册可合并到用户手

7、册中。另外对于B/S架构的软件系统还需在概要设计说明书与详细设计说明书中补充网页地图。如下例： username&password yes no以下是各主要文档的参考格式及提纲，文档编制者可以作为参考指导文档的编制，提纲中如果某些地方不需要说明的项可以省略。软件需求分析说明书 -软件需求说明书的编制是为了使用户和软件开发者双方对该软件的初始规定有一个共同的理解， 使之成为整个开发工作的基础。编制软件需求说明书的内容要求如下：1引言11编写目的说明编写这份软件需求说明书的目的，指出预期的读者。12背景 说明： a待开发的软件系统的名称；b本项目的任务提出者、开发者、用户及实现该软件的计算中心或计

8、算机网络；C该软件系统同其他系统或其他机构的基本的相互来往关系。 13定义列出本文件中用到的专门术语的定义和外文首字母组词的原词组。14参考资料 列出用得着的参考资料，如：a本项目的经核准的计划任务书或合同、上级机关的批文；b属于本项目的其他已发表的文件；c本文件中各处引用的文件、资料、包括所要用到的软件开发标准。 列出这些文件资料的标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料的来源。2任务概述 21目标 叙述该项软件开发的意图、应用目标、作用范围以及其他应向读者说明的有关该软件开发的背景材料。解释被开发软件与其他有关软件之间的关系。如果本软件产品是一项独立的软件，而且全部内容

9、自含，则说明这一点。如果所定义的产品是一个更大的系统的一个组成部分，则应说明本产品与该系统中其他各组成部分之间的关系，为此可使用一张方框图来说明该系统的组成和本产品同其他各部分的联系和接口。|22用户的特点 列出本软件的最终用户的特点，充分说明操作人员、维护人员的教育水平和技术专长，以及本软件的预期使甩频度。这些是软件设计工作的重要约束23假定和约束列出进行本软件开发工作的假定和约束，例如经费限制、开发期限等。3需求规定 31对功能的规定用列表的方式（例如IPO表即输入、处理、输出表的形式），逐项定量和定性地叙述对软件所提出的功能要求，说明输入什么量、经怎样的处理、得到什么输出，说明软件应支持

10、的终端数和应支持的并行操作的用户数。 32对性能的规定321精度 说明对该软件的输入、输出数据精度的要求，可能包括传输过程中的精度。322时间特性要求 说明对于该软件的时间特性要求，如对：a响应时间；b更新处理时间；c数据的转换和传送时间；d解题时间； 等的要求。323灵活性 说明对该软件的灵活性的要求，即当需求发生某些变化时，该软件对这些变化的适应能力，如：a操作方式上的变化；b运行环境的变化； c同其他软件的接口的变化；d精度和有效时限的变化； e计划的变化或改进。 对于为了提供这些灵活性而进行的专门设计的部分应该加以标明。33输人输出要求解释各输入输出数据类型，并逐项说明其媒体、格式、数

11、值范围、精度等。对软件的数据输出及必须标明的控制输出量进行解释并举例，包括对硬拷贝报告（正常结果输出、状态输出及异常输出）以及图形或显示报告的描述。34数据管理能力要求 说明需要管理的文卷和记录的个数、表和文卷的大小规模，要按可预见的增长对数据及其分量的存储要求作出估算。 35故障处理要求列出可能的软件、硬件故障以及对各项性能而言所产生的后果和对故障处理的要求。36其他专门要求如用户单位对安全保密的要求，对使用方便的要求，对可维护性、可补充性、易读性、可靠性、运行环境可转换性的特殊要求等。 4运行环境规定 41设备 列出运行该软件所需要的硬设备。说明其中的新型设备及其专门功能，包括：a处理器型

12、号及内存容量；b外存容量、联机或脱机、媒体及其存储格式，设备的型号及数量；c输入及输出设备的型号和数量，联机或脱机； d数据通信设备的型号和数量；e功能键及其他专用硬件42支持软件 列出支持软件,包括要用到的操作系统、编译（或汇编）程序、测试支持软件等。43 接口说明该软件同其他软件之间的接口、数据通信协议等。44控制 说明控制该软件的运行的方法和控制信号，并说明这些控制信号的来源。数据库设计说明书 -1引言 11编写目的说明编写这份数据库设计说明书的目的，指出预期的读者。12背景说明：a说明待开发的数据库的名称和使用此数据库的软件系统的名称；b列出该软件系统开发项目的任务提出者、用户以及将安

13、装该软件和这个数据库的计算站（中心）。 13定义 列出本文件中用到的专门术语的定义、外文首字母组词的原词组。14参考资料 列出有关的参考资料： a本项目的经核准的计划任务书或合同、上级机关批文；b属于本项目的其他已发表的文件；c本文件中各处引用到的文件资料，包括所要用到的软件开发标准。 列出这些文件的标题、文件编号、发表日期和出版单位，说明能够取得这些文件的来源。2外部设计21标识符和状态联系用途，详细说明用于唯一地标识该数据库的代码、名称或标识符，附加的描述性信息亦要给出。如果该数据库属于尚在实验中、尚在测试中或是暂时使用的，则要说明这一特点及其有效时间范围。22使用它的程序列出将要使用或访

14、问此数据库的所有应用程序，对于这些应用程序的每一个，给出它的名称和版本号。 23约定陈述一个程序员或一个系统分析员为了能使用此数据库而需要了解的建立标号、标识的约定，例如 用于标识数据库的不同版本的约定和用于标识库内各个文卷、记录、数据项的命名约定等。 24专门指导向准备从事此数据库的生成、从事此数据库的测试、维护人员提供专门的指导，例如将被送入数据 库的数据的格式和标准、送入数据库的操作规程和步骤，用于产生、修改、更新或使用这些数据文卷的操 作指导。 如果这些指导的内容篇幅很长，列出可参阅的文件资料的名称和章条。25支持软件 简单介绍同此数据库直接有关的支持软件，如数据库管理系统、存储定位程

15、序和用于装入、生成、修 改、更新数据库的程序等。说明这些软件的名称、版本号和主要功能特性，如所用数据模型的类型、允许 的数据容量等。列出这些支持软件的技术文件的标题、编号及来源。 3结构设计31概念结构设计说明本数据库将反映的现实世界中的实体、属性和它们之间的关系等的原始数据形式，包括各数据项、记录、系、文卷的标识符、定义、类型、度量单位和值域，建立本数据库的每一幅用户视图。 32逻辑结构设计 说明把上述原始数据进行分解、合并后重新组织起来的数据库全局逻辑结构，包括所确定的关键字和属性、重新确定的记录结构和文卷结构、所建立的各个文卷之间的相互关系，形成本数据库的数据库管理员视图。 33物理结构

16、设计建立系统程序员视图，包括：a数据在内存中的安排，包括对索引区、缓冲区的设计；b所使用的外存设备及外存空间的组织，包括索引区、数据块的组织与划分；c访问数据的方式方法。4运用设计41数据字典设计 对数据库设计中涉及到的各种项目，如数据项、记录、系、文卷、模式、子模式等一般要建立起数据字典，以说明它们的标识符、同义名及有关信息。在本节中要说明对此数据字典设计的基本考虑。 42安全保密设计 说明在数据库的设计中，将如何通过区分不同的访问者、不同的访问类型和不同的数据对象，进行分别对待而获得的数据库安全保密的设计考虑。概要设计说明书 -1引言 11编写目的 说明编写这份概要设计说明书的目的，指出预

17、期的读者。12背景说明：a待开发软件系统的名称；b列出此项目的任务提出者、开发者、用户以及将运行该软件的计算站（中心）。13定义 列出本文件中用到的专门术语的定义和外文首字母组词的原词组。14参考资料 列出有关的参考文件，如：a本项目的经核准的计划任务书或合同，上级机关的批文；b属于本项目的其他已发表文件；c本文件中各处引用的文件、资料，包括所要用到的软件开发标准。 列出这些文件的标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料的来源。 2总体设计 21需求规定 说明对本系统的主要的输入输出项目、处理的功能性能要求，详细的说明可参见附录C。22运行环境简要地说明对本系统的运行环境（

18、包括硬件环境和支持环境）的规定，详细说明参见附录C。23基本设计概念和处理流程 说明本系统的基本设计概念和处理流程，尽量使用图表的形式。24结构 用一览表及框图的形式说明本系统的系统元素（各层模块、子程序、公用程序等）的划分，扼要说明每个系统元素的标识符和功能，分层次地给出各元素之间的控制与被控制关系25功能器求与程序的关系本条用一张如下的矩阵图说明各项功能需求的实现同各块程序的分配关系：26人工处理过程说明在本软件系统的工作过程中不得不包含的人工处理过程（如果有的话）。27尚未问决的问题说明在概要设计过程中尚未解决而设计者认为在系统完成之前必须解决的各个问题。3接口设计 31用户接口说明将向

19、用户提供的命令和它们的语法结构，以及软件的回答信息。32外部接口 说明本系统同外界的所有接口的安排包括软件与硬件之间的接口、本系统与各支持软件之间的接 口关系。33内部接口说明本系统之内的各个系统元素之间的接口的安排。4运行设计 41运行模块组合 说明对系统施加不同的外界运行控制时所引起的各种不同的运行模块组合，说明每种运行所历经的内部模块和支持软件。42运行控制 说明每一种外界的运行控制的方式方法和操作步骤。43运行时间说明每种运行模块组合将占用各种资源的时间。5系统数据结构设计 51逻辑结构设计要点 给出本系统内所使用的每个数据结构的名称、标识符以及它们之中每个数据项、记录、文卷和系的标识

20、、定义、长度及它们之间的层次的或表格的相互关系。 52物理结构设计要点给出本系统内所使用的每个数据结构中的每个数据项的存储要求，访问方法、存取单位、存取的物理关系（索引、设备、存储区域）、设计考虑和保密条件。 53数据结构与程序的关系 说明各个数据结构与访问这些数据结构的形式:6系统出错处理设计61出错信息 用一览表的方式说朗每种可能的出错或故障情况出现时，系统输出信息的形式、含意及处理方法。62补救措施说明故障出现后可能采取的变通措施，包括：a后备技术说明准备采用的后备技术，当原始系统数据万一丢失时启用的副本的建立和启动的技术，例如周期性地把磁盘信息记录到磁带上去就是对于磁盘媒体的一种后备技

21、术；b降效技术说明准备采用的后备技术，使用另一个效率稍低的系统或方法来求得所需结果的某些部分，例如一个自动系统的降效技术可以是手工操作和数据的人工记录；c恢复及再启动技术说明将使用的恢复再启动技术，使软件从故障点恢复执行或使软件从头开始重新运行的方法。 63系统维护设计 说明为了系统维护的方便而在程序内部设计中作出的安排，包括在程序中专门安排用于系统的检查与维护的检测点和专用模块。详细设计说明书 -1 引言 11编写目的说明编写这份详细设计说明书的目的，指出预期的读者。12背景 说明：a待开发软件系统的名称； b本项目的任务提出者、开发者、用户和运行该程序系统的计算中心。 13定义 列出本文件

22、中用到专门术语的定义和外文首字母组词的原词组。14参考资料 列出有关的参考资料，如： a本项目的经核准的计划任务书或合同、上级机关的批文；b属于本项目的其他已发表的文件；c本文件中各处引用到的文件资料，包括所要用到的软件开发标准。 列出这些文件的标题、文件编号、发表日期和出版单位，说明能够取得这些文件的来源。2程序系统的结构用一系列图表列出本程序系统内的每个程序（包括每个模块和子程序）的名称、标识符和它们之间 的层次结构关系。3程序1（标识符）设计说明 从本章开始，逐个地给出各个层次中的每个程序的设计考虑。以下给出的提纲是针对一般情况的。 对于一个具体的模块，尤其是层次比较低的模块或子程序，其

23、很多条目的内容往往与它所隶属的上一层 模块的对应条目的内容相同，在这种情况下，只要简单地说明这一点即可。 31程序描述 给出对该程序的简要描述，主要说明安排设计本程序的目的意义，并且，还要说明本程序的特点（如 是常驻内存还是非常驻？是否子程序？是可重人的还是不可重人的？有无覆盖要求？是顺序处理还是并发 处理卜等）。32功能 说明该程序应具有的功能，可采用IPO图（即输入一处理一输出图）的形式。33性能说明对该程序的全部性能要求，包括对精度、灵活性和时间特性的要求。34输人项 给出对每一个输入项的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、输入的方式。 数量和频度、输入媒体、输入数

24、据的来源和安全保密条件等等。3 5输出项 给出对每一个输出项的特性，包括名称、标识、数据的类型和格式，数据值的有效范围，输出的形式、 数量和频度，输出媒体、对输出图形及符号的说明、安全保密条件等等。36算法 详细说明本程序所选用的算法，具体的计算公式和计算步骤。37流程逻辑 用图表（例如流程图、判定表等）辅以必要的说明来表示本程序的逻辑流程。38接口用图的形式说明本程序所隶属的上一层模块及隶属于本程序的下一层模块、子程序，说明参数赋值和调用方式，说明与本程序相直接关联的数据结构（数据库、数据文卷）。 39存储分配 根据需要，说明本程序的存储分配。 310注释设计 说明准备在本程序中安排的注释，

25、如：a 加在模块首部的注释；b加在各分枝点处的注释； 对各变量的功能、范围、缺省条件等所加的注释； d对使用的逻辑所加的注释等等。 311限制条件 说明本程序运行中所受到的限制条件。312测试计划 说明对本程序进行单体测试的计划，包括对测试的技术要求、输入数据、预期结果、进度安排、人员职责、设备条件驱动程序及桩模块等的规定。313尚未解决的问题说明在本程序的设计中尚未解决而设计者认为在软件完成之前应解决的问题。4程序2（标识符）设计说明用类似3的方式，说明第2个程序乃至第N个程序的设计考虑。用户手册 -1引言 11编写目的说明编写这份用户手册的目的，指出预期的读者。 12背景说明：a这份用户手

26、册所描述的软件系统的名称；b该软件项目的任务提出者、开发者、用户（或首批用户）及安装此软件的计算中心。13定义列出本文件中用到的专门术语的定义和外文首字母组词的原词组。14参考资料 列出有用的参考资料，如：a项目的经核准的计划任务书或合同、上级机关的批文；b属于本项目的其他已发表文件； c本文件中各处引用的文件、资料，包括所要用到的软件开发标准。 列出这些文件资料的标题、文件编号、发表日期和出版单位，说明能够取得这些文件资料的来源。2用途21功能结合本软件的开发目的逐项地说明本软件所具有各项功能以及它们的极限范围。22性能221精度 逐项说明对各项输入数据的精度要求和本软件输出数据达到的精度，

27、包括传输中的精度要求。222时间特性 定量地说明本软件的时间特性，如响应时间，更新处理时间，数据传输、转换时间，计算时间等。 223灵活性 说明本软件所具有的灵活性，即当用户需求（如对操作方式、运行环境、结果精度、时间特性等的要求）有某些变化时，本软件的适应能力。 2 3 安 全保密说明本软件在安全、保密方面的设计考虑和实际达到的能力。3运行环境31 硬设备列出为运行本软件所要求的硬设备的最小配置，如： a处理机的型号、内存容量; b所要求的外存储器、媒体、记录格式、设备的型号和台数、联机脱机；c IO设备（联机脱机？）； d数据传输设备和转换设备的型号、台数。32支持软件说明为运行本软件所需要的支持软件，如：a操作系统的名称、版本号；b程序语言的编译汇编系统的名称和版本号；c数据库管理系统的名称和版本号；d其他支持软件。33数据结构 列出为支持本软件的运行所需要的数据库或数据文卷。4使用过程 在本章，首先用图表的形式说明软件的功能同系统的输入源机构、输出接收机构之间的关系。4 1安装与初始化 一步一步地说明为使用本软件而需进行的安装与初始化过程，包括程序的存储形式、安装与初始化过程中的全部操作命令、系统对这些命令的反应与答复。表征安装工