软件文档写作05文档表达1.ppt

文档涉众通常是系统文档或系统的既得利益者。因此，必须要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则，共有7条： 1.从读者的角度编写文档 2.避免出现不必要的重复 3.避免歧义 4.使用标准结构 5.记录基本原理 6.使文档保持更新，但频度不要过高 7.针对目标的适宜性对文档进行评审 这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。 * 4.1 软件文档的编制原则 1. 适应文档涉众 软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。 2. 应有必要的重复性 国家标准关于14种软件文档的内容要求显然存在某些重复。较明显的有2类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的梗概；另一类是各种文档的说明部分，如对功能性能的说明、对输入/输出的描述、系统配置环境等。 这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的相互参阅，提高文档的阅读效率。 3. 应具有一定的灵活性 鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活性。 第四章 软件文档表达 4.2 合理文档的7条规则 软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工能迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息，以便作为分析和决策的基础。 软件文档可能既是指示性文档，又是说明性文档。例如，对某些读者而言，它能指示什么应该是正确的，并对决策的制定施加限制；对另一些读者而言，它能说明什么是正确的，并详述已经就系统设计作出的决策。 因此，在对文档进行设计和评审的过程中，必须确保它能支持所有相关的需求。 了解文档的用途是一件极为重要的事情，因为这些用途确定了文档的形式。通常，软件文档基本具有3种用途： 1. 用作教育工具。包括向成员介绍系统。而成员可能是新的团队成员，或者是外部合作开发的分析师。 2. 用作涉众间的首要通信工具。这取决于涉众需要什么样的通信。下表给出了一些相关范例。 3. 作为系统分析的基础。为了支持分析工作，相关文档必须包含执行特定分析的必要信息。 表：相关文档和涉众通信需求 一致性检验的基础，目的是确保实现方案取得系统要求的实际成果 质量保证小组 确定产品家族中潜在的新成员是否处于范围之内，如果处于范围之内，距离多远 产品线管理者 组成开发团队的基础，这些团队分别对应已确认的工作任务、工作故障结构、计划、项目资源分配和由各团队执行的进展跟踪 管理人员 确定打算提供和要求的操作集，及其操作协议 必须和该系统进行交互的其他系统设计师 维护活动的起点，揭示预期更改会影响的区域 维护工程师 为必须组合在一起的部件指定正确的黑盒行为 测试工程师和集成工程师 为下游设计活动提供不能违背的限制和可利用的特权 实现者 解决资源争端，并确定性能和其它运行时资源消费预算 组成部分构架师和设计人员 就各种竞争性需求进行协商和权衡的论坛 代表客户(群)的需求工程师和系统分析师 通 信 涉 众 规则1：从读者的角度编写文档 这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给你带来以下优势： 1. 面向读者编写的文档，通常总会赢得读者。 2. 面向读者编写文档是一种礼貌的表现。 3. 避免使用令人生厌的专业术语。 4. 容易使文档变得易读、易理解，提高文档的“效率”。对于专业读者，好的文档将有利于系统设计思想、代码等的理解。 文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。 意识流：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。 执行流：按软件执行时的思维顺序捕捉思维，并加以记录。 编制文档时，首先应该明确文档的每一节将要回答(或说明/记录)什么问题，并对自己的文档进行有效的组织。 规则2：避免出现不必要的重复 要点：将每个信息都记录在确切的地方。 如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。 同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读者心生疑问，影响文档的可理解性。 但是，“避免不必要的重复”并不是机械的，必须墨守的成规。下列情况下，有时还是可以有必要的信息重复： 1. 如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引用的位置非常重要。 2. 有时，为了使表达更为明确，或者在表达两个不