软件文档写作14-用户文档

1、1 用户文档是软件开发人员为软件用户了解、使用、操作和维护等提供的详用户文档是软件开发人员为软件用户了解、使用、操作和维护等提供的详细资料。用户文档包括用户手册、操作手册和维护修改建议等。细资料。用户文档包括用户手册、操作手册和维护修改建议等。8.1 8.1 编制用户文档的基本要求编制用户文档的基本要求1. 1. 描述规范准确描述规范准确 用户文档的阅读对象通常是非计算机专业的人员，因此对用户有很强的实用户文档的阅读对象通常是非计算机专业的人员，因此对用户有很强的实用和指导意义。要求在描述内容、说明方法、提出见解时都应准确无误，恰如用和指导意义。要求在描述内容、说明方法、提出见解时都应准确无误

2、，恰如其分。文档需要反映哪些内容、如何描述、口气、分寸等，都应与编制目的、其分。文档需要反映哪些内容、如何描述、口气、分寸等，都应与编制目的、使用对象协调一致。用词应标准、统一、规范。使用对象协调一致。用词应标准、统一、规范。2. 2. 叙述简练生动叙述简练生动 用户文档应简洁、精炼，少用用户难懂的专业术语，并力求形象生动、图用户文档应简洁、精炼，少用用户难懂的专业术语，并力求形象生动、图文并茂，便于用户学习、理解和掌握软件的使用、操作。文并茂，便于用户学习、理解和掌握软件的使用、操作。3. 3. 语言严密平实语言严密平实 用户文档的价值在于科学性。文字表达必须合乎逻辑，才能有助于用户使用户文

3、档的价值在于科学性。文字表达必须合乎逻辑，才能有助于用户使用、操作软件。用、操作软件。4. 4. 内容系统完整内容系统完整 用户文档作为软件系统开发者和用户之间的界面，应能提供给用户关于软用户文档作为软件系统开发者和用户之间的界面，应能提供给用户关于软件整体结构、功能、安装、运行和操作的有关知识，并且用户文档的内容组织件整体结构、功能、安装、运行和操作的有关知识，并且用户文档的内容组织应该有系统性、层次性，使之成为软件使用、操作的清晰的应该有系统性、层次性，使之成为软件使用、操作的清晰的“交通图交通图”。28.2 8.2 软件常用表示形式软件常用表示形式 软件的表示方法为软件系统建立一个基本构

4、架，对理解软件，特别是对于软件的表示方法为软件系统建立一个基本构架，对理解软件，特别是对于软件的维护，将是非常重要的。软件的维护，将是非常重要的。1. 1. 容器模型容器模型 基于一个共享数据库的系统模型一般称为容器模型。基于一个共享数据库的系统模型一般称为容器模型。 如果系统的工作所使用的数据是围绕共享数据库进行的，这可以考虑采用如果系统的工作所使用的数据是围绕共享数据库进行的，这可以考虑采用容器模型来表达其系统结构。下图是一种集成容器模型来表达其系统结构。下图是一种集成CASECASE工具集的体系结构。工具集的体系结构。设计编辑器设计编辑器代码生成器代码生成器设计分析器设计分析器报告生成器

5、报告生成器程序编辑器程序编辑器设计转换器设计转换器项目存储项目存储 在上面的例子中，容器是被动的，对它的控制是由其它子系统完成的。在上面的例子中，容器是被动的，对它的控制是由其它子系统完成的。32. 2. 客户机客户机/ /服务器模型服务器模型 这个模型用于表示一个分布式系统，说明数据和加工过程在多个处理器这个模型用于表示一个分布式系统，说明数据和加工过程在多个处理器之间的分配。其例子如下图所示。之间的分配。其例子如下图所示。用户用户用户用户用户用户用户接口客户进程用户接口客户进程用户接口客户进程用户接口客户进程用户接口客户进程用户接口客户进程多媒体数据库服务器及中间件多媒体数据库服务器及中间

6、件图像图像服务器服务器视频视频服务器服务器声音声音服务器服务器文本文本服务器服务器图像图像数据库数据库视频视频数据库数据库声音声音数据库数据库文本文本数据库数据库43. 3. 抽象机模型抽象机模型 抽象机模型，也称分层模型，常用来表示子系统的接口模型。抽象机模型，也称分层模型，常用来表示子系统的接口模型。 将下图组织成一系列的层次，每一层次定义一组服务。一个著名的例子将下图组织成一系列的层次，每一层次定义一组服务。一个著名的例子是网络协议是网络协议OSIOSI参考模型。参考模型。 4. 4. 接口描述接口描述 大型系统总是分解成独立开发的一些子系统。因此，在软件描述中的一大型系统总是分解成独立

7、开发的一些子系统。因此，在软件描述中的一个必要成分就是定义子系统接口。接口的示意如下图。个必要成分就是定义子系统接口。接口的示意如下图。子系统子系统A子系统子系统B5 接口是一种抽象的概念，在面向对象的程序设计中，可以是一个类的公接口是一种抽象的概念，在面向对象的程序设计中，可以是一个类的公开的数据成员或成员函数，也可以是若干个类抽象出的接口对象。接口抽象开的数据成员或成员函数，也可以是若干个类抽象出的接口对象。接口抽象概念如图所示。概念如图所示。Class1- - 用于接口数据成员用于接口数据成员- - 其它数据成员其它数据成员Class2+ + 用于接口的成员函数用于接口的成员函数()()

8、+ + 其它成员函数其它成员函数()()Class3Class4interface接口对象接口对象Class5 接口描述主要包括三方面信息：接口描述主要包括三方面信息：- - 类型名类型名：即一组对象的名字：即一组对象的名字- - 接口语法接口语法：定义接口操作的名字、参数个数、参数类型及操作结果类型：定义接口操作的名字、参数个数、参数类型及操作结果类型- - 接口描述接口描述：对接口操作给出无二义的语法和语义解释：对接口操作给出无二义的语法和语义解释65. 5. 控制模型控制模型 控制模型控制模型在体系结构层次上描述子系统之间的控制流。有两在体系结构层次上描述子系统之间的控制流。有两种表示形

9、式：种表示形式：集中式控制集中式控制和和事件驱动控制事件驱动控制。 集中式控制集中式控制模型中，由一个称为系统控制器的子系统来负责模型中，由一个称为系统控制器的子系统来负责管理其它子系统的执行，模型工具子系统是管理其它子系统的执行，模型工具子系统是顺序执行顺序执行还是还是并发执并发执行行，而分成，而分成调用调用- -返回模型返回模型和和管理者模型管理者模型。 下图是一个调用下图是一个调用- -返回式集中控制模型的结构示例：返回式集中控制模型的结构示例：主程序主程序程序程序1程序程序2程序程序3程序程序1.1程序程序1.2程序程序3.1程序程序3.27 下图是一种实时系统的管理者集中控制模型的结

10、构示例：下图是一种实时系统的管理者集中控制模型的结构示例：故障处理器故障处理器传感器进程传感器进程传动装置进程传动装置进程计算进程计算进程系统控制系统控制用户界面用户界面 在基于事件驱动控制模型中，各个子系统都可以接受来自在基于事件驱动控制模型中，各个子系统都可以接受来自外部子系统的事件，并对此作出响应。外部子系统的事件，并对此作出响应。 典型的有典型的有广播型事件驱动控制模型广播型事件驱动控制模型和和中断型控制模型中断型控制模型。8 广播型事件驱动控制模型的结构示例如图：广播型事件驱动控制模型的结构示例如图：子系统子系统1子系统子系统2子系统子系统3子系统子系统n时间和消息处理器时间和消息处

11、理器 中断驱动型控制模型的结构示例如图：中断驱动型控制模型的结构示例如图：处理器处理器1 1处理器处理器2 2处理器处理器3 3处理器处理器4 4进程进程1 1进程进程2 2进程进程3 3进程进程4 4中断向量中断向量96. 6. 数据流模型数据流模型 数据流模型是描述系统数据处理的一种很直观的方式。下图是一个订单数据流模型是描述系统数据处理的一种很直观的方式。下图是一个订单处理的数据流图。处理的数据流图。完成订完成订单表单表完成订完成订单表单表完成订完成订单表单表验证订单验证订单记录订单记录订单订单明细订单明细+ +空白订单表空白订单表订单文件订单文件预算文件预算文件 下图是一个下图是一个C

12、ASECASE工具集的工具集的数据流图。数据流图。设计设计编辑器编辑器设计交叉设计交叉检查器检查器设计设计分析器分析器报告报告生成器生成器代码框架代码框架生成器生成器设计设计数据库数据库设计设计数据库数据库检查过检查过的设计的设计引用的引用的设计设计输出输出代码代码输入输入设计设计有效有效设计设计设计设计分析分析用户用户报告报告检查过检查过的设计的设计107. 7. 状态机模型状态机模型 状态机模型是一种描述系统对内或外部事件响应的行为模型，用来表示系状态机模型是一种描述系统对内或外部事件响应的行为模型，用来表示系统状态和事件，以及事件引发系统在状态之间的转换。下图是一个简单微波炉统状态和事件

13、，以及事件引发系统在状态之间的转换。下图是一个简单微波炉的状态机模型示例。的状态机模型示例。全功率全功率Do: set power=600等待等待Do: displaytime半功率半功率Do: set power=300设置时间设置时间Do:get numberExit:set time屏蔽屏蔽Do: displayWaiting激活激活Do: displayready等待等待Do: displaytime操作操作Do: operateopen全功率全功率半功率半功率全功率全功率半功率半功率机时器机时器机时器机时器门开门开门开门开门关门关开始开始取消取消系统出错系统出错数字数字118. 8.

14、 数据模型数据模型 绝大多数的软件系统都要使用数据库，因此，系统建模的一项重要工作绝大多数的软件系统都要使用数据库，因此，系统建模的一项重要工作就是定义系统处理的逻辑结构。数据模型就是要表达这样的一个结构。就是定义系统处理的逻辑结构。数据模型就是要表达这样的一个结构。 数据模型可以表示为一个数据模型可以表示为一个有向图有向图，包含一系列不同类型的结点，结点之，包含一系列不同类型的结点，结点之间的连线表示结点之间的关系，每个结点有结点标示和若干属性描述。下图间的连线表示结点之间的关系，每个结点有结点标示和若干属性描述。下图是一个由一组结点和一组关联构成的是一个由一组结点和一组关联构成的ERAER

15、A数据模型，表是对应的数据字典。数据模型，表是对应的数据字典。设计设计NamedescriptionC-dateM-date标签标签Nametexticon链接链接Nametype链接链接Nametype有结有结点点n1有标有标签签11is an有链有链接接有标有标签签1nn1有链有链接接12链接链接12ERAERA图所对应的数据字典图所对应的数据字典名名 字字描描 述述类类 型型日日 期期has-labels在结点或关联实体和类型标签实体间的在结点或关联实体和类型标签实体间的1:n关系关系关系关系2005-12-30label存放结点或关联的结构化的或非结构化的信息。标存放结点或关联的结构化

16、的或非结构化的信息。标签由一个图标签由一个图标(可能是一个透明方块可能是一个透明方块)和相关的文本和相关的文本表示表示实体实体2005-12-30link表示设计实体的结点间的表示设计实体的结点间的1:1关系，关联具有类型和关系，关联具有类型和名字名字关系关系2005-12-30name(label)每个标签具有一个说明类型的名字，该名字在设计每个标签具有一个说明类型的名字，该名字在设计中的标签类型必须唯一中的标签类型必须唯一属性属性2005-12-30name(node)每个结点名字在整个设计中必须唯一，名字可以长每个结点名字在整个设计中必须唯一，名字可以长达达64个字符个字符属性属性200

17、5-12-309. 9. 对象模型对象模型 对象模型是一种映射真实世界中实体及对其操作的自然方法。对象模型对象模型是一种映射真实世界中实体及对其操作的自然方法。对象模型既可以表达系统数据，又可以表达对数据的处理。因此，对象模型可以看作既可以表达系统数据，又可以表达对数据的处理。因此，对象模型可以看作是数据流模型和数据模型的结合。是数据流模型和数据模型的结合。 下面的图是用下面的图是用UMLUML描述对象类的例子。图中，每个矩形表示一个对象类，描述对象类的例子。图中，每个矩形表示一个对象类，其中包括对象名字、对象类中的属性、对象类的中操作。向上的空三角箭头其中包括对象名字、对象类中的属性、对象类

18、的中操作。向上的空三角箭头表示继承。表示继承。13- Catalogue number- Acquisition- Cost- Type- Status- Number of copies+ Acquire()+ Catalogue()+ Dispose()+ Issue()+ Return()- Author- Edition- Publication date- ISBN- Title- Publisher- Title- Medium- Year- Issue- Version- Platform- Director- Date of release- Distributor图书馆系统的部分类层次图书馆系统的部分类层次14 除了通过继承来组织系统，对象类还可以由其它的对象组合而成，称为除了通过继承来组织系统，对象类还可以由其它的对象组合而成，称为对象成员。这种关系称为对象的聚合，使用菱形表示聚合关系。如图所示的对象成员。这种关系称为对象的聚合，使用菱形表示聚合关系。如图所示的是课程的聚合对象表示。是课程的聚合对象表示。课程课程Course ti