软件文档写作

第3章软件文档写作为什么需要软件文档？文档是计算机软件产品的重要组成部分，没有文档就不成其为软件，也更不能成为软件产品。软件文档是一种重要的软件工程技术资料。如系统分析文档、设计文档、版本说明文档……软件文档的规范编制，在软件开发工作中占有突出的地位和相当大的工作量。高质量、高效率的编制、分发、管理、维护文档，及时的变更、修正、扩充和使用文档，对于软件产品的设计开发、发行使用、变更维护、转让移植、二次开发等，对于充分发挥软件产品的效益，都有着重要的意义。软件文档写作是为了记录目标系统的定义、规划、分析、研究、设计、开发、应用等各个阶段的设计思想和研究成果。文档——某种数据媒体和其中所记录的数据。文档具有永久性，并可供人或机器阅读，通常指专供人阅读的东西。文档作为计算机软件的重要组成部分，告诉用户如何操作和维护系统，提供关于未来改进和重新实施所需的信息，在开发人员、维护人员、管理人员、用户与计算机之间起着重要的桥梁作用。维护人员管理人员计算机软件用户桥梁作用开发人员软件文档与使用者的关系软件开发中产生的各类文档面向不同的用户，而软件用户应该得到的文档也在商业合同中有明确规定。软件文档的使用对象开发人员维护人员管理人员用户可行性研究报告项目开发计划软件需求说明书数据要求说明书概要设计说明书详细设计说明书数据库设计说明书测试计划测试分析报告设计说明书测试分析报告模块开发卷宗可行性研究报告项目开发计划模块开发卷宗开发进度月报项目开发总结报告用户手册操作手册软件文档编制与软件生存期的关系软件文档的编制是随着软件生存期各个阶段工作的开展而适时进行的。其中，有的仅反映某一阶段的工作，有的则需要跨越多个阶段的工作。如下表：可行性研究与计划需求分析软件设计编码与单元测试集成测试运行与维护可行性研究报告√项目开发计划√√软件需求说明书√数据要求说明书√测试计划√√概要设计说明书√详细设计说明书√数据库设计说明书√模块开发卷宗√√用户手册√√√操作手册√√测试分析报告√开发进度月报√√√√√项目总结报告√维护和修改建议√软件文档最终需要回答读者关心的下列问题：1.为什么要开发、维护或修改这个软件？(Why)2.工作目标要满足哪些需求？(What)3.需求应如何实现？(How)4.开发、维护或修改的工作应由谁来完成？(Who)5.开发工作的时间如何安排？(When)6.开发工作在什么环境中实现，所需信息从何而来？(Where)为什么(Why)做什么(What)怎么做(How)谁来做(Who)何时做(When)何处做(Where)可行性研究报告√√项目开发计划√√√软件需求说明书√√数据要求说明书√√测试计划√√√概要设计说明书√详细设计说明书√数据库设计说明书√模块开发卷宗√用户手册√操作手册√测试分析报告√开发进度月报√√项目总结报告√维护和修改建议√√√√√软件文档的涉众软件文档涉众主要有以下几类：开发人员、维护人员、管理人员、营销人员和用户。具体的，上述各类涉众又可以再细分，如开发人员可以细分为系统定义和分析工程师、系统架构师、系统设计师、代码工程师、系统集成工程师、测试工程师……有不少软件文档的涉众，既是文档涉众，又是文档的编制者。如系统构架师是系统需求规格说明书的涉众，但同时他自己的工作成果又是通过编制系统构架文档来进行传递。我们这里所说的软件文档涉众，是指那些对某一类或某种软件文档有特殊需求和期望的涉众。下表是各类文档涉众以及他们需要的文档类型(部分)：开发人员维护人员管理人员营销人员用户可行性研究报告√√√项目开发计划√√√软件需求说明书√√数据要求说明书√测试计划√√概要设计说明书√√详细设计说明书√√数据库设计说明书√√模块开发卷宗√√用户手册√√操作手册√√测试分析报告√√开发进度月报√项目总结报告√维护和修改建议√产品市场宣传资料√√√讨论题1.你现在是否明确，为什么需要软件文挡？2.你能用自己的语言描述清楚什么是软件文挡，以及它的作用、地位和涉众吗？对文档编制的质量要求1.针对性编档前即能根据涉众对象，按不同文档类型、不同涉众层次、不同分发策略，确定编档目的、目标、标准、方案、计划和资源。2.精确性文档行文应十分确切、一致，没有多义、矛盾等现象。3.清晰性文档力求简洁，表述清晰，如有可能，则配以适当图表，以增强可阅读性。4.完整性任何文档都是完整的、独立的，是自成体系的。5.灵活性不同软件项目的规模和复杂程度有着许多实际差别，不能一样看待。应根据具体的软件开发项目，决定编制的文档种类。当所开发的软件系统非常大时，一种文档可以分成几卷编写。应根据任务的规模、复杂性、项目负责人对该软件的开发过程及运行环境所需详细程度的判断，确定文档的详细程度。对国标GB8567—88《计算机软件产品开发文件编制指南》所建议的所有条款都可以扩展，进一步细分，以适应需要；反之，如果条款中有些细节并非必需，也可以根据实际情况压缩合并。程序的设计表现形式，可以使用程序流程图、判定表、程序描述语言（PDL)或问题分析图（PAD)等。国标对文档的表现形式没有规定或限制。可以使用自然语言，也可以使用形式化的语言。国标给出的文档种类通常已能满足项目内容的表达，但当项目有特殊要求时，可以创建新的文档种类，以满足使用。6.可追溯性软件开发各阶段编制的文档与各自对应阶段完成的工作有紧密联系，相邻阶段的文档也会有一定的继承关系，因此，必要时相关文档能做到跟踪追查。1.用求和法确定应编制的文档该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。例题：随着杭州逐步具备国际会展中心的基本功能，各类国际国内、专业民用展览，各种演出活动以及各种形式的会议、培训等活动将会越来越多，参与活动的人士也会有各种各样，有的需要购买入场券，有的需要安排住宿，有的需要安排会议活动(如大会发言、小型研讨、专题讲座、新闻发布等，及场所)，有的需要安排游览，也有的需要安排翻译、领导接见或其它会务服务。对于部分会展、演出活动还需要在筹办期间拟订邀请宾客名单，发出邀请信，并对回执进行管理。购票、邀请宾客及被邀宾客回执均可以在分布式环境中完成，会议期间的活动安排可以在网上实时发布，甚至部分会议活动被安排在网上实时直播。根据以上叙述，规划设计一个简单的会务管理系统，完成上述功能的管理需求。编号因素因素取值123451创新程度没有－在不同设备上重编程序有限－只是具有更严格的要求很多－具有新的接口大量－应用新的现代开发技术重大－应用先进的开发和管理技术2通用程度很强的限制－单一项目有限制－功能的范围是参量化的有限的灵活性，允许格式上有些变化多用途、灵活的格式、有主题领域很灵活－能在不同设备上处理范围广泛的主题3应用范围局部单位(团以下)本地应用(师级)行业推广(军级)全国推广(大军区)国际项目(全军范围)4应用环境的变化没有很少偶尔有经常不断5设备复杂性单机、常规处理单机、常规处理、扩充的外设系统多机、标准的外设系统多机、复杂准的外设系统和显示主机控制系统多机自动I/O6参加开发人数1～2人3～5人6～13人11～18人19以上7开发投资(人月)66～3636～120120～3603608重要程度一般数据处理常规过程控制人身安全单位成败国家安危9完成程序修改的平均时间2周以上1～2周3～7天1～3天24小时以内10数据I/O平均时间2周以上1～2周1～7天1～24小时1小时以内11编程语言高级语言高级语言带少量的汇编高级语言带相当多的汇编汇编语言机器语言12并行软件开发没有有限中等程度很多全部使用求和法的具体过程是：(1)按前表中的12个因素衡量所要开发的程序，得到每个因素的值。在该问题中，我们通过分析可以得知各个因素的得分如下：(1)创新程度＝1(7)开发投资(人月)＝1(2)通用程度＝3(8)重要程度＝1(3)应用范围＝2(9)完成程序修改的平均时间＝3(4)应用环境的变化＝1(10)数据I/O平均时间＝5(5)设备复杂性＝3(11)编程语言＝1(6)参加开发人数＝1(12)并行软件开发＝2(2)把衡量所得的各个因素的值相加，得总和之值。在本例中，这个值∑＝24可行性研究报告项目开发计划软件需求说明书数据要求说明书概要设计说明书详细设计说明书测试计划用户手册操作手册测试分析报告开发进度月报项目开发总结程序维护手册12～18√√*√16～26√√**√√√√√√24～38√√√**√√√√√√√36～50√√√**√√√√√√√√48～60√√√**√√√√√√√√√(3)根据总和之值，从下表中，查出应编制的文档种类。表中：*，表示此文档应编制，但不必太正规；**，表示应根据所开发软件的实际需要来确定是否需要编制此文档。现在，可以依据表格，获知本例需要编制的文档种类，总共有10种之多。2.根据软件规模大小确定应编制的文档为了避免在软件开发过程中文档编制的不足或过分，也为了避免前一种方法中对某些因素的把握出现误判，一个简便的方法是，把对软件文档的编制要求同软件的规模联系起来。这就是本例的出发点。这里，我们把软件的规模分为四级：(1)小规模软件，源码行数小于5000；(2)中规模软件，源码行数约10000～50000；(3)大规模软件，源码行数约100000～500000；(4)超大规模软件，源码行数大于500000。对此，相应规模软件应该编制的文档种类，参见下表：小规模软件中规模软件大规模软件超大规模软件软件需求与开发计划项目开发计划可行性报告对应大规模软件所规定的文档种类，再做进一步细分项目开发计划软件需求说明软件需求说明数据要求说明测试计划测试计划软件设计说明软件设计说明概要设计说明详细设计说明数据库设计说明使用说明使用说明用户手册操作手册测试分析报告模块开发卷宗模块开发卷宗测试分析报告测试分析报告项目开发总结开发进度月报开发进度月报项目开发总结项目开发总结3.2软件文档的编写步骤四个步骤：①准备工作②确定写作内容③编写定稿④更新完善3.3如何写好计算机软件文档3.3.1做好准备3.3.2讲究文风3.3.3注重表达3.3.4加强文档编写使用的组织管理3.3.5文档写作中值得注意的几个问题3.3.1做好准备1.深入理解系统和用户在理解系统和用户方面主要应解决三个问题：第一，理解目标系统；第二，理解用户(这里的用户包含两层含义：其一是计算机系统用户，其二是有关计算机软件文档的读者或使用者）；第三，将对系统和用户的理解进行分析比较。2.明确写作目的(1)不同的编写目的要求不同的编写方法(2)不同读者对文档有不同要求•以系统分析设计人员为主要读者的文档。这类文档主要有系统原始模型、系统分析报告、系统需求说明等。这类读者一般包括用户的高层人员和计算机系统设计开发的高层人员。编写这类文档特别需要注意的问题是：保证所编写文档必须让用户和计算机人员都能全面正确地理解其含义，并保证无二义性。此时必须注意用词的内含与外延的一致，尽量少用专业词语。•以系统开发人员为主要读者的文档。这类文档主要有系统概要设计、系统详细设计等。这类读者不同程度地具有一定的计算机专业知识和技能，对系统所处理的内容和用户的有关情况了解相对较少。编写这类文档时，对计算机方面的有关叙述可以完全采用专业术语，不必有过多过细的解释，而对涉及系统处理对象及用户方面的内容应写得较全面详细。•以系统维护人员为主要读者的文档。这类文档主要指系统维护文档等，读者一般包括计算机专业人员和用户两类。这类文档必须提供系统总体功能及每一个具体功能实现的细节，并保证可读性，必要的话应提供系统流程、数据流程等更为详尽的资料。必须做到通过阅读这类文档可以全面、准确、详细地理解系统的有关情况，同时注意专业性与通俗性并重。•以系统使用人员为主要读者的文档。这类文档主要指用户手册、参考手册、操作手册及用于宣传系统情况的文档等，这类文档可称为用户文档。这类文档