软件文档写作标准讲义

软件文档写作⑴问题定义 （书面）⑵可行性分析报告 （书面）⑶项目开发计划 （书面）⑷需求规格说明书 （书面）⑸总体设计报告 （书面）⑹系统测试计划 （书面）⑺项目验收方案 （书面）

要求：根据软件工程技术和项目管理理念，在组内合理分工，协同工作。软件文档文档是计算机软件产品的重要组成部分，没有文档就不成其为软件，也更不能成为软件产品。软件文档是一种重要的软件工程技术资料。如系统分析文档、设计文档、版本说明文档……软件文档的规范编制，在软件开发工作中占有突出的地位和相当大的工作量。高质量、高效率的编制、分发、管理、维护文档，及时的变更、修正、扩充和使用文档，对于软件产品的设计开发、发行使用、变更维护、转让移植、二次开发等，对于充分发挥软件产品的效益，都有着重要的意义。软件文档的分类基于软件生存期方法，可以从形式上将软件文档大致分成两类：软件开发过程中需要填写的各种图表，及应编制的各种技术文件或管理资料。软件文档根据其产生和使用的范围，主要划分为3大类：开发文档、用户文档和管理文档。软件文档开发文档用户文档管理文档可行性研究报告项目开发计划软件需求说明书数据库设计说明书概要设计说明书详细设计说明书用户手册操作手册软件需求说明书数据要求说明书项目开发计划模块开发卷宗开发进度月报测试计划测试分析报告项目开发总结报告开发文档用户文档软件文档的使用对象开发人员维护人员管理人员用户可行性研究报告项目开发计划软件需求说明书数据要求说明书概要设计说明书详细设计说明书数据库设计说明书测试计划测试分析报告设计说明书测试分析报告模块开发卷宗可行性研究报告项目开发计划模块开发卷宗开发进度月报项目开发总结报告用户手册操作手册可行性研究与计划需求分析软件设计编码与单元测试集成与测试运行与维护可行性研究报告√项目开发计划√√软件需求说明书√数据要求说明书√测试计划√√概要设计说明书√详细设计说明书√数据库设计说明书√模块开发卷宗√√用户手册√√√操作手册√√测试分析报告√开发进度月报√√√√√项目总结报告√维护和修改建议√软件生存周期各个阶段与各种文档编制的关系为什么(Why)做什么(What)怎么做(How)谁来做(Who)何时做(When)何处做(Where)可行性研究报告√√项目开发计划√√√软件需求说明书√√数据要求说明书√√测试计划√√√概要设计说明书√详细设计说明书√数据库设计说明书√模块开发卷宗√用户手册√操作手册√测试分析报告√开发进度月报√√项目总结报告√维护和修改建议√√√√√文档所回答的问题软件工程标准化和软件文档标准软件工程标准编制的层次根据软件工程标准制定的机构和标准适用的范围，可分为5个层次：国际标准:ISO国际标准化组织国家标准:GB中国ANSI美国BS英国JIS日本行业标准:IEEE企业(机构)标准:IBM项目(课题)标准:CIMS类型标准名称标准号基础标准软件工程术语GB/T11457-1989信息处理——数据流程、程序流程图、系统结构图、程序网络图、系统资源图的文件编制符号及约定GB/T1526-1989软件工程标准分类法GB/T15538-1995信息处理——程序构造及其表示法的约定GB/T13502-1992信息处理——单命中判定表规范GB/T15535-1995(ISO5806)信息处理系统——计算机系统配置图符号及其约定GB/T14085-1993(ISO8790)开发标准信息技术——软件生存期过程GB/T8566-1995软件支持环境GB/T15853-1995信息处理——按记录组处理顺序文卷的程序流程GB/T15697-1995(ISO6593)软件维护指南GB/T14079-1993文档标准计算机软件产品开发文档编制指南GB/T8567-1988计算机软件需求说明编制指南GB/T9385-1988计算机软件测试文档编制规范GB/T9386-1988软件文档管理指南GB/T16680-1996管理标准计算机软件配置管理计划规范GB/T12505-1990信息技术——软件产品评价质量特性及其使用指南GB/T16260-1996计算机软件质量保证计划规范GB/T12504-1990计算机软件可靠性和可维护性管理GB/T14394-1993文档表达合理文档的7条规则1.从读者的角度编写文档2.避免出现不必要的重复3.避免歧义4.使用标准结构5.记录基本原理6.使文档保持更新，但频度不要过高7.针对目标的适宜性对文档进行评审

下表是各类文档涉众以及他们需要的文档类型(部分)：开发人员维护人员管理人员营销人员用户可行性研究报告√√√项目开发计划√√√软件需求说明书√√数据要求说明书√测试计划√√概要设计说明书√√详细设计说明书√√数据库设计说明书√√模块开发卷宗√√用户手册√√操作手册√√测试分析报告√√开发进度月报√项目总结报告√维护和修改建议√产品市场宣传资料√√√（1）用求和法确定应编制的文档该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。编号因素因素取值123451创新程度没有－在不同设备上重编程序有限－只是具有更严格的要求很多－具有新的接口大量－应用新的现代开发技术重大－应用先进的开发和管理技术2通用程度很强的限制－单一项目有限制－功能的范围是参量化的有限的灵活性，允许格式上有些变化多用途、灵活的格式、有主题领域很灵活－能在不同设备上处理范围广泛的主题3应用范围局部单位(团以下)本地应用(师级)行业推广(军级)全国推广(大军区)国际项目(全军范围)4应用环境的变化没有很少偶尔有经常不断5设备复杂性单机、常规处理单机、常规处理、扩充的外设系统多机、标准的外设系统多机、复杂准的外设系统和显示主机控制系统多机自动I/O6参加开发人数1~2人3～5人6～13人11~18人19以上7开发投资(人月)<66~3636~120120~360>3608重要程度一般数据处理常规过程控制人身安全单位成败国家安危9完成程序修改的平均时间2周以上1～2周3～7天1～3天24小时以内10数据I/O平均时间2周以上1～2周1～7天1～24小时1小时以内11编程语言高级语言高级语言带少量的汇编高级语言带相当多的汇编汇编语言机器语言12并行软件开发没有有限中等程度很多全部然后，将上表衡量所得的各个因素的值相加，得总和值。再根据下表，确定应编制的文档种类。可行性研究报告项目开发计划软件需求说明书数据要求说明书概要设计说明书详细设计说明书测试计划用户手册操作手册测试分析报告开发进度月报项目开发总结程序维护手册12～18√√*√16～26√√**√√√√√√24～38√√√**√√√√√√√36～50√√√**√√√√√√√√48～60√√√**√√√√√√√√√文档的种类因素值总和表中：*，表示此文档应编制，但不必太正规；**，表示应根据所开发软件的实际需要来确定是否需要编制此文档。（2）根据软件规模大小确定应编制的文档为了避免在软件开发过程中文档编制的不足或过分，也为了避免前一种方法中对某些因素的把握出现误判，一个简便的方法是，把对软件文档的编制要求同软件的规模联系起来。这就是本例的出发点。这里，我们把软件的规模分为四级：(1)小规模软件，源码行数小于5000；(2)中规模软件，源码行数约10000～50000；(3)大规模软件，源码行数约100000～500000；(4)超大规模软件，源码行数大于500000。对此，相应规模软件应该编制的文档种类，参见下表：小规模软件中规模软件大规模软件超大规模软件软件需求与开发计划项目开发计划可行性报告对应大规模软件所规定的文档种类，再做进一步细分项目开发计划软件需求说明软件需求说明数据要求说明测试计划测试计划软件设计说明软件设计说明概要设计说明详细设计说明数据库设计说明使用说明使用说明用户手册操作手册测试分析报告模块开发卷宗模块开发卷宗测试分析报告测试分析报告项目开发总结开发进度月报开发进度月报项目开发总结项目开发总结对于源码行数在5000～10000、50000～100000的软件，其文档编制的种类介于两级之间，可由项目负责人根据项目的具体情况，参照下表规定确定。开发文档概述开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细设计描述(程序逻辑、程序间相互关系、数据格式和存储等)。基本的软件开发文档主要有：可行性研究和项目任务书需求规格说明功能规格说明设计规格说明，包括程序和数据规格说明开发计划软件集成和测试计划质量保证计划、标准、进度安全和测试信息

[项目名称]可行性研究报告拟制人______________审核人______________批准人______________[200年月日]

可行性研究报告模板的例子：1.引言1.1编写目的1.2背景1.3定义1.4参考资料2.可行性研究的前提2.1要求2.2目标2.3条件、假定和限制2.4进行可行性研究的方法2.5评价尺度3.对现有系统的分析3.1处理流程和数据流程3.2工作负荷3.3费用开支3.4人员3.5设备3.6局限性4.所建议的系统4.1对所建议系统的说明4.2处理流程和数据流程4.3改进之处4.4影响4.4.1对设备的影响4.4.2对软件的影响4.4.3对用户单位机构的影响4.4.4对系统运行过程的影响4.4.5对开发的影响4.4.6对地点和设施的影响4.4.7对经费开支的影响

4.5局限性4.6技术条件方面的可行性5.可选择的其他系统方案5.1可选择的系统方案15.2可选择的系统方案26.投资及效益分析6.1支出6.1.1基本建设投资6.1.2其他一次性支出6.1.3非一次性支出6.2收益6.2.1一次性收益6.2.2非一次性收益6.2.3不可定量的收益6.3收益／投资比6.4投资回收周期6.5敏感性分析7.社会因素方面的可行性

7.1法律方面的可行性7.2使用方面的可行性8.结论软件需求文档的内容1．引言1.1编写的目的说明编写这份需求说明书的目的，指出预期的读者。1.2背景待开发的系统的名称；本项目的任务提出者、开发者、用户；该系统同其他系统或其他机构的基本的相互来往关系。1.3定义列出本文件中用到的专门术语的定义和外文首字母组词的原词组。1.4参考资料列出用得着的参考资料。2．任务概述2.1目标叙述该系统开发的意图、应用目标、作用范围以及其他应向读者说明的有关该系统开发的背景材料。解释被开发系统与其他有关系统之间的关系。2.2用户的特点列出本系统的最终用户的特点，充分说明操作人员、维护人员的教育水平和技术专长，以及本系统的预期使用频度。2.3假定和约束列出进行本系统开发工作的假定和约束。3．需求规定3.1对功能的规定用列表的方式，逐项定量和定性地叙述对系统所提出的功能要求，说明输入什么量、经怎么样的处理、得到什么输出，说明系统的容量,包括系统应支持的终端数和应支持的并行操作的用户数等指标。3.2对性能的规定3.2.1精度说明对该系统的输入、输出数据精度的要求，可能包括传输过程中的精度。3.2.2时间特性要求说明对于该系统的时间特性要求。3.2.3灵活性说明对该系统的灵活性的要求，即当需求发生某些变化时，该系统对这些变化的适应能力。3.3输入输出要求解释各输入输出数据类型，并逐项说明其媒体、格式、数值范围、精度等。对系统的数据输出及必须标明的控制输出量进行解释并举例。3.4数据管理能力要求(针对软件系统)说明需要管理的文卷和记录的个数、表和文卷的大小规模，要按可预见的增长对数据及其分量的存储要求作出估算。3.5故障处理要求列出可能的软件、硬件故障以及对各项性能而言所产生的后果和对故障处理的要求。3.6其他专门要求如用户单位对安全保密的要求，对使用方便的要求，对可维护性、可补充性、易读性、可靠性、运行环境可转换性的特殊要求等。4．运行环境规定4.1设备列出运行该软件所需要的硬设备。说明其中的新型设备及其专门功能，包括：处理器型号及内存容量外存容量、联机或脱机、媒体及其存储格式，设备的型号及数量输入及输出设备的型号和数量，联机或脱机；数据通信设备的型号和数量功能键及其他专用硬件4.2支持软件列出支持软件，包括要用到的操作系统、编译程序、测试支持软件等。4.3接口说明该系统同其他系统之间的接口、数据通信协议等。4.4控制说明控制该系统的运行的方法和控制信号，并说明这些控制信号的来源。

软件概要设计文档结构化表现形式：层次图示例字处理系统输入输出编辑存储检索格式化编目录添加删除插入修改合并列表简单的层次图缺乏追踪性，而HIPO图可以弥补此一缺点。1.结构化表现形式结构化表现形式：HIPO图实际上，HIPO图是由H图和IPO图两部分组成：H图就是层次图；和H图每个方框相对应的，应该有一张IPO图描述该方框代表的模块的处理过程。如下图，是一个带编号的H图的例，具有可追踪性。字处理系统输出2.0输入1.0存储4.0编辑3.0格式化6.0检索5.0编目录7.0删除3.2添加3.1修改3.4插入3.3列表3.6合并3.5IPO图使用的符号既少又简单，能够方便的描述数据输入、处理和输出之间的关系。如下图是一个主文档更新的IPO例子。程序名：模块名：编制者：日期：页号：输入处理输出旧的主文件事务文件1.检验主记录2.校验事务记录3.更新主记录有效的主记录有效的事务记录更新后的主记录图中，箭头清楚的指出了数据通信的情况。结构化表现形式：结构图Yourdon提出的结构图是进行软件结构设计的另一个有力的表达方法。而且，结构图较之层次图有更强的描述力。产生最佳解得到好输入计算最佳解输出结果读输入编辑输入结果格式化显示结果好输入解好输入解原始输入原始输入编辑结束解解的格式化格式化的解结构化表现形式：结构图结构图还有一些附加的符号，用以表示模块的选择调用和循环调用。如下图，左图是选择调用，右图是循环调用。

MAB判定为真时调用模块A，否则调用模块BMACB模块M循环调用模块A、B、C2、面向对象设计表现形式（1）面向对象设计(OOD)的4个部分这4个部分是问题域、人机交互部分、任务管理部分和数据管理部分。如下图所示。主题层类及对象层结构层属性层问题域部分人机交互部分任务管理部分数据管理部分-问题域部分：OOD根据需求分析中对问题域的描述，针对实现要求进行必要的整补和调整。其重点是：重用类设计、组合问题域专用类、调整继承的支持级别、提供数据管理部分以及增加底层细节。-人机交互部分设计：突出人如何命令系统，及系统如何向用户提交信息。尤其对非计算机专业用户如何提交信息。-任务管理部分设计：设计策略要点是识别并设计任务，加上包含在每个任务中的服务。-设计管理部分设计：该部分主要是为了隔离数据管理方案对系统设计表达的影响。设计既包含数据存放方法的设计，也包含相应服务的设计。①继承机制的表示通常将父类放在上面，将子类放在下面。如左图AB父类子类派生继承下图是表示鸡、鸭、猫、狗和动物之间的继承关系。动物家禽类宠物鸡鸭鹅狗猫②聚集关系的表示若类B的定义将类A的对象作为数据成员，则B和A之间是一种聚集关系，其表示方法如下图所示。汽车B轮胎A子午线轮胎③对象关联的表示关联源对象关联指针被关联对象属性Next关联对象指针属性Next关联对象指针属性Next关联对象指针被关联对象被关联对象内嵌关联结构表示外嵌关联结构表示A类对象：A1A类对象：A1A类对象：A2B类对象：B1B类对象：B2B类对象：B3AB关联类B类AB类对象关联表A类对象标识B类对象标识关联对象A1 B1 AB1A1 B2 AB2A2 B1 AB3… … …④注册/观察器的表示一种将新的信息一对一的迅速传送或通知给相关对象的对象协作机制。特别在分布式环境中，对象通信代价很高时，这是一种高效的手段，在网络软件设计时常用。见下图例。生产者CollectionClientAttach()Detach()GetData()Generator()Notify()客户生产者*Gen客户()～客户()Update()SetGen()……Notify()……ClientUpdate()…GenAttach()GenDetach()1..n⑤虚拟设备的表示虚拟设备是操作系统的一个重要概念。使用这种概念，可以为在不同设备上实现相同功能，或以相同操作接口访问不同设备提供可能和方便。如图ApplicationCanvasDraw()Line()Circle()Rectangle()TextOut()…DrawSpaceDraw()Line()Circle()Rectangle()TextOut()…PrinterDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…PrinterPrewDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…ScreenWinDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…OtherGDI⑥代理结构的表示代理是一种在应用和被访问对象之间建立的桥梁或关口。通过代理的虚拟作用，达到控制对象访问的目的。代理具有的作用或特性可以包括间接性、委托性、临时替代性、虚拟性、安全性/保护性、远程性和多源性。下图是代理模式的实现结构表示的例子。ApplicationObjectService()…ActualObjectService()…Object*anObjectService()…ProxyanObjectReturnanObjectService()网络代理连接的表示例子：应用代理远程对象多源代理连接的例子应用代理问题求解对象1对象n对象2……连接连接连接连接软件详细设计文档软件详细设计文档详细设计在概要设计之后，其工作重点是考虑实现各个模块的规定功能，表达的是模块内部的逻辑关系、数据结构和模块接口细节等，表达的方法主要有程序流程图、N-S图、PAD图、PDL语言以及判定表、树等。①程序流程图程序流程图(ProgramFlowChart)的5种基本控制结构：(1)顺序结构(sequentialstructure)(2)选择结构(selectivestructure)ABPBAFT(3)先判定型循环结构(while-loopstructure)(4)后判定型循环结构(until-loopstructure)TPSFFSTP(5)多情况选择(casestructure)TA1FP=1TA2FP=2…TAnFP=n②N-S图：顺序ABPFTAB选择PFTBDo-WhilePSWhile型循环Do-UntilPSUntil型循环Case型选择P12nA1A2An子过程调用A③PAD图(ProblemAnalysisDiagram)：日立公司，1973年提出。为