软件用户文档

软件用户文档第一页，共三十四页，编辑于2023年，星期三2023/6/1417.1软件用户文档用户文档是软件开发人员为软件用户了解、使用、操作和维护等提供的详细资料。用户文档包括用户手册、操作手册和维护修改建议等。7.1编制用户文档的基本要求1.描述规范准确

用户文档的阅读对象通常是非计算机专业的人员，因此对用户有很强的实用和指导意义。要求在描述内容、说明方法、提出见解时都应准确无误，恰如其分。文档需要反映哪些内容、如何描述、口气、分寸等，都应与编制目的、使用对象协调一致。用词应标准、统一、规范。2.叙述简练生动

用户文档应简洁、精炼，少用用户难懂的专业术语，并力求形象生动、图文并茂，便于用户学习、理解和掌握软件的使用、操作。3.语言严密平实

用户文档的价值在于科学性。文字表达必须合乎逻辑，才能有助于用户使用、操作软件。4.内容系统完整

用户文档作为软件系统开发者和用户之间的界面，应能提供给用户关于软件整体结构、功能、安装、运行和操作的有关知识，并且用户文档的内容组织应该有系统性、层次性，使之成为软件使用、操作的清晰的“交通图”。2023/6/142第二页，共三十四页，编辑于2023年，星期三7.2软件常用表示形式软件的表示方法为软件系统建立一个基本构架，对理解软件，特别是对于软件的维护，将是非常重要的。1.容器模型基于一个共享数据库的系统模型一般称为容器模型。如果系统的工作所使用的数据是围绕共享数据库进行的，这可以考虑采用容器模型来表达其系统结构。下图是一种集成CASE工具集的体系结构。设计编辑器代码生成器设计分析器报告生成器程序编辑器设计转换器项目存储在上面的例子中，容器是被动的，对它的控制是由其它子系统完成的。2023/6/143第三页，共三十四页，编辑于2023年，星期三2.客户机/服务器模型这个模型用于表示一个分布式系统，说明数据和加工过程在多个处理器之间的分配。其例子如下图所示。用户用户用户用户接口客户进程用户接口客户进程用户接口客户进程多媒体数据库服务器及中间件图像服务器视频服务器声音服务器文本服务器……图像数据库视频数据库声音数据库文本数据库2023/6/144第四页，共三十四页，编辑于2023年，星期三3.抽象机模型抽象机模型，也称分层模型，常用来表示子下图的接口模型。将下图组织成一系列的层次，每一层次定义一组服务。一个著名的例子是网络协议OSI参考模型。下图是一个版本管理下图的抽象机模型的结构示例。4.接口描述大型系统总是分解成独立开发的一些子系统。因此，在软件描述中的一个必要成分就是定义子系统接口。接口的示意如下图。子系统A子系统B2023/6/145第五页，共三十四页，编辑于2023年，星期三接口是一种抽象的概念，在面向对象的程序设计中，可以是一个类的公开的数据成员或成员函数，也可以是若干个类抽象出的接口对象。接口抽象概念如图所示。Class1-用于接口数据成员-其它数据成员Class2+用于接口的成员函数()+其它成员函数()Class3Class4《interface》接口对象Class5接口描述主要包括三方面信息：-类型名：即一组对象的名字-接口语法：定义接口操作的名字、参数个数、参数类型及操作结果类型-接口描述：对接口操作给出无二义的语法和语义解释2023/6/146第六页，共三十四页，编辑于2023年，星期三5.控制模型控制模型在体系结构层次上描述子系统之间的控制流。有两种表示形式：集中式控制和事件驱动控制。集中式控制模型中，由一个称为系统控制器的子系统来负责管理其它子系统的执行，模型工具子系统是顺序执行还是并发执行，而分成调用-返回模型和管理者模型。下图是一个调用-返回式集中控制模型的结构示例：主程序程序1程序2程序3程序1.1程序1.2程序3.1程序3.22023/6/147第七页，共三十四页，编辑于2023年，星期三下图是一种实时系统的管理者集中控制模型的结构示例：故障处理器传感器进程传动装置进程计算进程系统控制用户界面在基于事件驱动控制模型中，各个子系统都可以接受来自外部子系统的事件，并对此作出响应。典型的有广播型事件驱动控制模型和中断型控制模型。2023/6/148第八页，共三十四页，编辑于2023年，星期三广播型事件驱动控制模型的结构示例如图：子系统1子系统2子系统3子系统n…时间和消息处理器中断驱动型控制模型的结构示例如图：处理器1处理器2处理器3处理器4进程1进程2进程3进程4中断向量2023/6/149第九页，共三十四页，编辑于2023年，星期三6.数据流模型数据流模型是描述系统数据处理的一种很直观的方式。下图是一个订单处理的数据流图。完成订单表完成订单表完成订单表验证订单记录订单订单明细+空白订单表订单文件预算文件下图是一个CASE工具集的数据流图。设计编辑器设计交叉检查器设计分析器报告生成器代码框架生成器设计数据库设计数据库检查过的设计引用的设计输出代码输入设计有效设计设计分析用户报告检查过的设计2023/6/1410第十页，共三十四页，编辑于2023年，星期三7.状态机模型状态机模型是一种描述系统对内或外部事件响应的行为模型，用来表示系统状态和事件，以及事件引发系统在状态之间的转换。下图是一个简单微波炉的状态机模型示例。全功率Do:setpower=600等待Do:displaytime半功率Do:setpower=300设置时间Do:getnumberExit:settime屏蔽Do:display‘Waiting’激活Do:display‘ready’等待Do:displaytime操作Do:operateopen全功率半功率全功率半功率计时器计时器门开门关门关开始取消系统出错数字2023/6/1411第十一页，共三十四页，编辑于2023年，星期三8.数据模型绝大多数的软件系统都要使用数据库，因此，系统建模的一项重要工作就是定义系统处理的逻辑结构。数据模型就是要表达这样的一个结构。数据模型可以表示为一个有向图，包含一系列不同类型的结点，结点之间的连线表示结点之间的关系，每个结点有结点标示和若干属性描述。下图是一个由一组结点和一组关联构成的ERA数据模型，表是对应的数据字典。设计NamedescriptionC-dateM-date标签Nametexticon链接Nametype链接Nametype有结点n1有标签11isan有链接有标签1nn1有链接12链接2023/6/1412第十二页，共三十四页，编辑于2023年，星期三ERA图所对应的数据字典名字描述类型日期has-labels在结点或关联实体和类型标签实体间的1:n关系关系2005-12-30label存放结点或关联的结构化的或非结构化的信息。标签由一个图标(可能是一个透明方块)和相关的文本表示实体2005-12-30link表示设计实体的结点间的1:1关系，关联具有类型和名字关系2005-12-30name(label)每个标签具有一个说明类型的名字，该名字在设计中的标签类型必须唯一属性2005-12-30name(node)每个结点名字在整个设计中必须唯一，名字可以长达64个字符属性2005-12-309.对象模型对象模型是一种映射真实世界中实体及对其操作的自然方法。对象模型既可以表达系统数据，又可以表达对数据的处理。因此，对象模型可以看作是数据流模型和数据模型的结合。下面的图是用UML描述对象类的例子。图中，每个矩形表示一个对象类，其中包括对象名字、对象类中的属性、对象类的中操作。向上的空三角箭头表示继承。2023/6/1413第十三页，共三十四页，编辑于2023年，星期三-CataloguenumberAcquisitionCostType-Status-Numberofcopies+Acquire()+Catalogue()+Dispose()+Issue()+Return()-Author-Edition-Publicationdate-ISBN-Title-Publisher-Title-Medium-Year-Issue-Version-Platform-Director-Dateofrelease-Distributor图书馆系统的部分类层次2023/6/1414第十四页，共三十四页，编辑于2023年，星期三除了通过继承来组织系统，对象类还可以由其它的对象组合而成，称为对象成员。这种关系称为对象的聚合，使用菱形表示聚合关系。如图所示的是课程的聚合对象表示。课程CoursetitleNumberYearInstructor作业Credits幻灯片Slides课堂笔记Text录像带Tapeids练习ProblemsDescription解答TextDiagrams2023/6/1415第十五页，共三十四页，编辑于2023年，星期三对象行为建模用序列图来表示。如图，描述一组对象上的一个序列图，操作由带标签的箭头指示，操作顺序是自上而下。读者目录图书馆项目服务器查找显示发行发行许可接受许可打包交付电子科目的发放——对象行为建模2023/6/1416第十六页，共三十四页，编辑于2023年，星期三7.3用户手册

软件的质量是由多个方面构成的，用户手册也是衡量软件质量的一个重要标准。特别是目前软件需求快速增长，市场迅速扩张的时期，不少软件开发者过于注重软件的功能、性能，而忽略了软件作为产品的其它方面的质量，而用户手册的质量问题尤为突出。一个优秀的用户手册可以帮助用户快速入门，是用户正确、充分使用软件的前提。对于开发者来说，质量符合要求的用户手册，至少可以减少用户培训和售后服务的投入。所以，对软件开发者来说，应该充分认识软件产品用户手册的重要性，提高用户手册的质量，以促进软件产品质量的整体提高。一个质量存在问题的某产品用户手册的例子。2023/6/1417第十七页，共三十四页，编辑于2023年，星期三1.用户手册的完整性

在实际使用中经常发现，很多软件由于开发过于仓促，在付诸使用时，用户手册中经常缺少关于某些方面的说明，有时缺少的还是十分重要的内容，让用户使用时，感到困难，甚至是无所适从。而质量良好的用户手册，至少应该是能够包括软件产品的所有相关内容，能够指导用户顺利的安装、设置和使用软件。因此，保证内容的全面性和完整性是把握用户手册质量的重要方面。2.用户手册的描述与软件实际功能的一致性

用户手册的内容不仅要保证其全面性和完整性，还要确保它与一起发行的软件版本的实际功能相一致。现实情况是，由于开发企业产品研发管理和产品版本管理方面存在的问题，产生用户手册描述内容和软件实际运行情况不一致，造成用户使用中的困惑和误解，进而影响软件的正常使用。2023/6/1418第十八页，共三十四页，编辑于2023年，星期三3.用户手册的易理解性

由于软件产品的用户往往对计算机方面的专业知识了解不多，对软件运行缺少实际的脑际映像，因此，用户手册的可理解性，是其质量的重要指标。对于软件使用中那些关键的、重要的、文字难表述清楚的，或者使用图表方法可以简化描述，增加可理解性的内容，应该采用图表或附有图表的方式描述。优秀的用户手册应该是图文并举，易读、易理解、易对照。4.用户手册应提供学习操作的实例

一个没有软件运行和操作实例的用户手册，对于用户来说，其实并没有太大的帮助。例如，软件中关于系统网络参数配置的说明，如果没有具体实例的辅助演示，相信绝大多数没有多少网络知识的用户是很难胜任的。一个优秀的用户手册，不仅要对软件主要功能和关键操作提供应用实例，而且实例的描述还应做到详细、充分，易于理解，实例最好由图示的方法描述。2023/6/1419第十九页，共三十四页，编辑于2023年，星期三5.用户手册的印刷与包装质量

用户手册作为商品化软件产品的重要组成内容，其纸张、印刷、装订、包装等的质量，包括版面、封面等的设计质量，手册和软件应用类型的吻合程度等，都将直接影响软件的形象、市场可接受度和最终的销售业绩。另外，用户手册不同于用户使用说明书，它除了向用户提供基本的产品操作方法，还要提供很多与产品相关的其它信息。主要的有以下方面：-介绍：软件的基本情况-用途：介绍软件的适用范围、功能、性能主要及其特点-运行环境：介绍软件最基本的和推荐的运行配置、软件安装说明、参数设定等，以及可能引起的和系统的冲突，解决途径等-使用过程：向用户介绍软件具体的使用方法-相关信息：必要的开发者信息，软件注册、升级途径等2023/6/1420第二十页，共三十四页，编辑于2023年，星期三7.4操作手册

操作手册是指导软件具体操作的工具书。操作手册涉及软件设计完成后的以后所关心的有关操作的内容。由于操作的项目不同，操作手册的内容和形式也有所不同。在形式上，有技术指导书，也有操作规程等类型。内容上，伸缩的余地较大。但一般而言，操作手册的内容主要应包括：1.引言。主要简介软件的外围特性、软件名称、开发单位、专用名称，概述软件内部的一些结构，介绍手册涉及的技术、设备或产品的特点、用途、使用对象、指导的内容，以及手册的编排格式等，一些规模较大的手册，还要介绍手册的使用方法和检索示例，使读者对手册和软件产品都有一个大概的了解。写作上，要求简明扼要，叙述全面、真实，读者读后能感受到对手册和软件产品的一个提纲式的了解。2023/6/1421第二十一页，共三十四页，编辑于2023年，星期三2.操作原理。这部分内容是对操作对象或过程的主要性质或步骤的解释，为操作者提供理论依据和操作基础。这部分内容要求适合操作者的专业水平，一般不宜过于专深，内容描述可结合公式、框图、图表等，要求易于阅读、理解。3.操作说明。介绍操作的具体步骤和要求，是操作手册的核心部分。步骤的组织结构一般按每一步骤分点说明。操作说明的辅助叙述方法主要有图解、框图、程序、表格等。这些辅助表述方法有时也会成为手册内容的主要表述形式。如操作过程的说明。操作说明要求简练、准确、形象、清晰、易懂，表述内容应与系统实际操作过程对应一致，语句多采用短句和主动语态，经常是一个动作、一个步骤为一个编号单位。2023/6/1422第二十二页，共三十四页，编辑于2023年，星期三4.注意事项。注意事项是指系统操作过程中应该注意的内容。注意事项和故障排除也经常放在操作说明中。但更多的时候，为了强调，将其单独列出，还有那些不属于基本操作的内容，也可放在这一部分。如软件与运行环境的维护、保管、技术故障的判断、排除、操作质量的分析等。5.附录。主要用于非操作说明内容的补充叙述。如运行环境的配套设备、技术指标的误差范围、非常规过程部分和远程操作部分等，以及在其它方面的应用或其典型操作的示例等。附录也经常提供一些与软件产品密切相关的理论、技术、方法、工具、资料、数据及其发明、创作或提供者的出处、来源、介绍等资料，包括技术文档、资料的引用列表等。2023/6/1423第二十三页，共三十四页，编辑于2023年，星期三7.5维护修改文档

根据软件生命周期的阶段理论，软件投入运行后，在相当长的时间里，由于业务、政策、市场、法规、管理、技术等方面的发展和变化，都会使得软件应用机构的业务经历着持续不断的变化，这些变化或者产生了新的需求，或者需要修改原先的软件需求。再好的软件系统，都会随着系统应用领域业务的变化而变化。因此，软件在其生命周期中是会不断的进行着维护修改工作的。1.软件运行系统的结构

对运行中的软件进行维护修改，将涉及技术和社会的双重因素。这不仅是由客观的工程准则决定，还会受到软件运行环境和机构策略的影响。如图，软件运行系统的不同逻辑部分，会产生各自不同的相互影响。2023/6/1424第二十四页，共三十四页，编辑于2023年，星期三支持软件应用软件业务策略和规则硬件系统应用数据业务过程使用使用使用约束嵌入知识运行在运行在软件运行系统的例子：图中，各部分的含义如下：-硬件系统：当时的硬件系统现在可能已过时，或者维护费用过高-支持软件：系统运行所依赖的操作系统、数据库系统、与硬件相关的实用程序、驱动程序、编译系统等，现在可能已无法得到生产厂家的支持-应用软件：应用系统是由多个程序组成的，并且这些程序是独立的，在不同的时段开发的-应用数据：在系统以往的运行历史中，积累了大量的数据，不同文档的数据可能不一致或有重复-业务过程：业务过程受到业务策略和规则的约束，对应用软件提出具体的需求-业务策略和规则：规定了业务执行的规则和流程2023/6/1425第二十五页，共三十四页，编辑于2023年，星期三上面软件运行系统的示意图可以进一步抽象为右图所示的层次结构。从图中可以看到，每一层依赖于其下方的一层，层与层之间有接口。因此，对系统的一个层次进行维护或变更，势必引起其它各层作出相应的变更。业务过程应用软件应用软件支持软件硬件一个应用软件通常包含有多个不同的程序，不同的程序针对不同的数据操作，有些数据还可能为多个程序共享。如图，程序变更影响到数据，也影响到其它程序的变更。程序1程序2程序3程序4程序5程序6程序7文件1文件2文件3文件4文件5文件6本例说明，当需要对软件进行修改、变更时，应评估其影响，并慎重地提出建议，以提交审批。2023/6/1426第二十六页，共三十四页，编辑于2023年，星期三2.维护修改方案软件的维护、修改需要资金的支持，需要对投资做精心安排，以期获得好的回报。因此，对所维护修改的软件系统作出客观的分析和评估，制定合理、恰当的维护修改方案，是维护取得成功的前提。根据实际软件维护可能的类型，可以有下面几种可选的维护方案：-彻底抛弃现有系统。当系统不能对现有业务过程产生有效作用时选择-继续维护现有系统。当系统运行平稳，能够继续发挥作用，用户也没有大的变更要求时，可选择此方案-转换系统以改善其可维护性。当系统质量应经常变更，或系统的功能、性能增加及改善后，现运行环境已不敷适应，并且系统维护修改的需求仍然是经常性的时候，应选择此方案-以一新系统代替现系统。当新的硬件环境无法使现软件系统继续正常运行；或虽现系统仍然能使用，但新开发系统的成本已很合理时，可考虑采用此方案-综合方案。根据实际情况，选择上面几种方案进行综合维护工作2023/6/1427第二十七页，共三十四页，编辑于2023年，星期三3.维护过程与记载

在通常情况下，一个规范的维护过程，都应有规范的结构化维护文档的生成机制。由于维护过程是由一系列变更请求所触发的，这些变更请求可以来自于系统用户、管理层或者是客户。从抽象层面看，所有维护过程都有相同的基本活动，包括变更分析、版本规划、系统实现和交付使用。下图描述了系统维护过程的概况。变更请示影响分析版本规划变更实现缺陷修补平台适应系统增强系统发布2023/6/1428第二十八页，共三十四页，编辑于2023年，星期三在维护过程的变更实现阶段，应该修改系统描述、实际和实现，以反映对系统所做的变更。要对提出的反映系统变更的新需求进行详细分析，明确变更的内容。变更的过程由于变更涵义在变更分析的早期阶段的不清晰性，而变得曲折反复，因此，对变更需求应进行反复的修改和有效性验证，然后再进入相应的组件设计和实现阶段，最后通过测试，完成系统变更维护。其过程如下图所示。变更提议需求分析需求更新变更开发2023/6/1429第二十九页，共三十四页，编辑于2023年，星期三软件生命周期的所有阶段的文档，对软件维护工作都是十分重要的。这些文档将作为评估维护技术的有效性，确定软件产品的“优良”程度，以及确定维护的实际代价等的重要依据。因此，维护过程内容的记载应该要确定。下面是维护记载的基本内容参考：-程序标识-源语句数-机器指令条数-使用的程序设计语言-程序安装的日期-自从安装以来程序运行的次数-自从安装以来程序失效的次数-程序变动的层次标识-因程序变动而增加的源语句数-因程序变动而减少的源语句数-每个改动耗费的人时数-程序改动的日期-软件工程师的名字-维护要求表的标识-维护类型-维护开始和完成的日期-累计用于维护的人时数-与完成的维护相联系的纯效益2023/6/1430第三十页，共三十四页，编辑于2023年，星期三