软件文档写作15-用户文档2

1 8 3用户手册软件的质量是由多个方面构成的 用户手册也是衡量软件质量的一个重要标准 特别是目前软件需求快速增长 市场迅速扩张的时期 不少软件开发者过于注重软件的功能 性能 而忽略了软件作为产品的其它方面的质量 而用户手册的质量问题尤为突出 一个优秀的用户手册可以帮助用户快速入门 是用户正确 充分使用软件的前提 对于开发者来说 质量符合要求的用户手册 至少可以减少用户培训和售后服务的投入 所以 对软件开发者来说 应该充分认识软件产品用户手册的重要性 提高用户手册的质量 以促进软件产品质量的整体提高 一份质量良好的软件产品用户手册应该满足以下几点重要方面 2 1 用户手册的完整性在实际使用中经常发现 很多软件由于开发过于仓促 在付诸使用时 用户手册中经常缺少关于某些方面的说明 有时缺少的还是十分重要的内容 让用户使用时 感到困难 甚至是无所适从 而质量良好的用户手册 至少应该是能够包括软件产品的所有相关内容 能够指导用户顺利的安装 设置和使用软件 因此 保证内容的全面性和完整性是把握用户手册质量的重要方面 2 用户手册的描述与软件实际功能的一致性用户手册的内容不仅要保证其全面性和完整性 还要确保它与一起发行的软件版本的实际功能相一致 现实情况是 由于开发企业产品研发管理和产品版本管理方面存在的问题 产生用户手册描述内容和软件实际运行情况不一致 造成用户使用中的困惑和误解 进而影响软件的正常使用 3 3 用户手册的易理解性由于软件产品的用户往往对计算机方面的专业知识了解不多 对软件运行缺少实际的脑际映像 因此 用户手册的可理解性 是其质量的重要指标 对于软件使用中那些关键的 重要的 文字难表述清楚的 或者使用图表方法可以简化描述 增加可理解性的内容 应该采用图表或附有图表的方式描述 优秀的用户手册应该是图文并举 易读 易理解 易对照 4 用户手册应提供学习操作的实例一个没有软件运行和操作实例的用户手册 对于用户来说 其实并没有太大的帮助 例如 软件中关于系统网络参数配置的说明 如果没有具体实例的辅助演示 相信绝大多数没有多少网络知识的用户是很难胜任的 一个优秀的用户手册 不仅要对软件主要功能和关键操作提供应用实例 而且实例的描述还应做到详细 充分 易于理解 实例最好由图示的方法描述 4 5 用户手册的印刷与包装质量用户手册作为商品化软件产品的重要组成内容 其纸张 印刷 装订 包装等的质量 包括版面 封面等的设计质量 手册和软件应用类型的吻合程度等 都将直接影响软件的形象 市场可接受度和最终的销售业绩 另外 用户手册不同于用户使用说明书 它除了向用户提供基本的产品操作方法 还要提供很多与产品相关的其它信息 主要包括以下方面 介绍 软件的基本情况 用途 介绍软件的适用范围 功能 性能主要及其特点 运行环境 介绍软件最基本的和推荐的运行配置 软件安装说明 参数设定等 以及可能引起的和系统的冲突 解决途径等 使用过程 向用户介绍软件具体的使用方法 相关信息 必要的开发者信息 软件注册 升级途径等 5 8 4操作手册操作手册是指导软件具体操作的工具书 操作手册涉及软件设计完成后的以后所关心的有关操作的内容 由于操作的项目不同 操作手册的内容和形式也有所不同 在形式上 有技术指导书 也有操作规程等类型 内容上 伸缩的余地较大 但一般而言 操作手册的内容主要应包括 1 引言 主要简介软件的外围特性 软件名称 开发单位 专用名称 概述软件内部的一些结构 介绍手册涉及的技术 设备或产品的特点 用途 使用对象 指导的内容 以及手册的编排格式等 一些规模较大的手册 还要介绍手册的使用方法和检索示例 使读者对手册和软件产品都有一个大概的了解 写作上 要求简明扼要 叙述全面 真实 读者读后能感受到对手册和软件产品的一个提纲式的了解 6 2 操作原理 这部分内容是对操作对象或过程的主要性质或步骤的解释 为操作者提供理论依据和操作基础 这部分内容要求适合操作者的专业水平 一般不宜过于专深 内容描述可结合公式 框图 图表等 要求易于阅读 理解 3 操作说明 介绍操作的具体步骤和要求 是操作手册的核心部分 步骤的组织结构一般按每一步骤分点说明 操作说明的辅助叙述方法主要有图解 框图 程序 表格等 这些辅助表述方法有时也会成为手册内容的主要表述形式 如操作过程的说明 操作说明要求简练 准确 形象 清晰 易懂 表述内容应与系统实际操作过程对应一致 语句多采用短句和主动语态 经常是一个动作 一个步骤为一个编号单位 7 4 注意事项 注意事项是指系统操作过程中应该注意的内容 注意事项和故障排除也经常放在操作说明中 但更多的时候 为了强调 将其单独列出 还有那些不属于基本操作的内容 也可放在这一部分 如软件与运行环境的维护 保管 技术故障的判断 排除 操作质量的分析等 5 附录 主要用于非操作说明内容的补充叙述 如运行环境的配套设备 技术指标的误差范围 非常规过程部分和远程操作部分等 以及在其它方面的应用或其典型操作的示例等 附录也经常提供一些与软件产品密切相关的理论 技术 方法 工具 资料 数据及其发明 创作或提供者的出处 来源 介绍等资料 包括技术文档 资料的引用列表等 8 8 5维护修改文档根据软件生命周期的阶段理论 软件投入运行后 在相当长的时间里 由于业务 政策 市场 法规 管理 技术等方面的发展和变化 都会使得软件应用机构的业务经历着持续不断的变化 这些变化或者产生了新的需求 或者需要修改原先的软件需求 再好的软件系统 都会随着系统应用领域业务的变化而变化 因此 软件在其生命周期中是会不断的进行着维护修改工作的 1 软件运行系统的结构对运行中的软件进行维护修改 将涉及技术和社会的双重因素 这不仅是由客观的工程准则决定 还会受到软件运行环境和机构策略的影响 如图 软件运行系统的不同逻辑部分 会产生各自不同的相互影响 9 软件运行系统的例子 图中 各部分的含义如下 硬件系统 当时的硬件系统现在可能已过时 或者维护费用过高 支持软件 系统运行所依赖的操作系统 数据库系统 与硬件相关的实用程序 驱动程序 编译系统等 现在可能已无法得到生产厂家的支持 应用软件 应用系统是由多个程序组成的 并且这些程序是独立的 在不同的时段开发的 应用数据 在系统以往的运行历史中 积累了大量的数据 不同文档的数据可能不一致或有重复 业务过程 业务过程受到业务策略和规则的约束 对应用软件提出具体的需求 业务策略和规则 规定了业务执行的规则和流程 10 上面软件运行系统的示意图可以进一步抽象为右图所示的层次结构 从图中可以看到 每一层依赖于其下方的一层 层与层之间有接口 因此 对系统的一个层次进行维护或变更 势必引起其它各层作出相应的变更 业务过程 应用软件 应用软件 支持软件 硬件 一个应用软件通常包含有多个不同的程序 不同的程序针对不同的数据操作 有些数据还可能为多个程序共享 如图 程序变更影响到数据 也影响到其它程序的变更 本例说明 当需要对软件进行修改 变更时 应评估其影响 并慎重地提出建议 以提交审批 11 2 维护修改方案软件的维护 修改需要资金的支持 需要对投资做精心安排 以期获得好的回报 因此 对所维护修改的软件系统作出客观的分析和评估 制定合理 恰当的维护修改方案 是维护取得成功的前提 根据实际软件维护可能的类型 可以有下面几种可选的维护方案 彻底抛弃现有系统 当系统不能对现有业务过程产生有效作用时选择 继续维护现有系统 当系统运行平稳 能够继续发挥作用 用户也没有大的变更要求时 可选择此方案 转换系统以改善其可维护性 当系统质量因经常变更 或系统的功能 性能增加及改善后 现运行环境已不再适应 并且系统维护修改的需求仍然是经常性的时候 应选择此方案 以一新系统代替现系统 当新的硬件环境无法使现软件系统继续正常运行 或虽现系统仍然能使用 但新开发系统的成本已很合理时 可考虑采用此方案 综合方案 根据实际情况 选择上面几种方案进行综合维护工作 12 3 维护过程与记载在通常情况下 一个规范的维护过程 都应有规范的结构化维护文档的生成机制 由于维护过程是由一系列变更请求所触发的 这些变更请求可以来自于系统用户 管理层或者是客户 从抽象层面看 所有维护过程都有相同的基本活动 包括变更分析 版本规划 系统实现和交付使用 下图描述了系统维护过程的概况 13 在维护过程的变更实现阶段 通常修改系统描述 设计和实现 以反映对系统所做的变更 要对提出的反映系统变更的新需求进行详细分析 明确变更的内容 变更的过程由于变更含义在变更分析的早期阶段的不清晰性 而变得曲折反复 因此 对变更需求应进行反复的修改和有效性验证 然后再进入相应的组件再设计和维护实现阶段 最后通过测试 完成系统变更维护 其过程如下图所示 14 软件生命周期的所有阶段的文档 对软件维护工作都是十分重要的 这些文档将作为评估维护技术的有效性 确定软件产品的 优良 程度 以及确定维护的实际代价等的重要依据 因此 维护活动过程的内容应详细记载 下面是维护记载的基本内容参考 程序标识 源语句数 机器指令条数 使用的程序设计语言 程序安装的日期 自从安装以来程序运行的次数 自从安装以来程序失效的次数 程序变动的层次标识 因程序变动而增加的源语句数 因程序变动而减少的源语句数 每个改动耗费的人时数 程序改动的日期 软件工程师的名字 维护要求表的标识 维护类型 维护开始和完成的日期 累计用于维护的人时数 与完成的维护相联系的纯效益 15 4 软件维护建议维护过程应该可以视同一个缩微了的软件开发过程 因此 在软件维护过程中和维护完成后 都因编制规范的文档 如为软件使用者提供内容详实 完整的软件维护手册 软件维护手册主要包括软件系统说明 程序模块说明 操作环境 支持软件的说明 维护过程的说明等 维护手册的软件使用部分 还应介绍系统功能 性能及操作在维护后的变化 维护申请表应该是一张标准化格式的表格 用以表达软件维护修改的要求 描述维护修改的建议 维护申请表也称软件问题报告表 由提出维护活动的用户负责填写 完整的描述导致出现错误的环境 包括输入数据 全部输出数据 以及其它有关信息 对于适应性或完善性维护要求 还应该提供简短的需求说明书 16 编写软件维护修改建议由用户提交的维护申请表是编写维护修改建议书的基础 通过维护管理员和系统管理员 评价用户提交的维护申请表 确定用户维护要求的合理性 明确维护范围和内容 制定软件组织内部应该执行的软件维护修改建议 软件维护修改建议主要包括以下信息 满足维护申请表中提出的维护要求所需要的工作量 维护要求的性质 该项维护修改要求的优先次序 与维护修改有关的数据 17 评价维护修改软件生命周期所有阶段生成的文档是评价维护修改活动的依据 对维护活动的评价可以做一些定量的度