软件文档写作05-文档表达1知识讲稿.pptVIP

4.1 软件文档的编制原则 1. 适应文档涉众 软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。 2. 应有必要的重复性 国家标准关于14种软件文档的内容要求显然存在某些重复。较明显的有2类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的梗概；另一类是各种文档的说明部分，如对功能性能的说明、对输入/输出的描述、系统配置环境等。 这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的相互参阅，提高文档的阅读效率。 3. 应具有一定的灵活性 鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活性。;4.2 合理文档的7条规则 软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工能迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息，以便作为分析和决策的基础。 软件文档可能既是指示性文档，又是说明性文档。例如，对某些读者而言，它能指示什么应该是正确的，并对决策的制定施加限制；对另一些读者而言，它能说明什么是正确的，并详述已经就系统设计作出的决策。 因此，在对文档j进行设计和评审的过程中，必须确保它能支持所有相关的需求。 了解文档的用途是一件极为重要的事情，因为这些用途确定了文档的形式。通常，软件文档基本具有3种用途： 1. 用作教育工具。包括向成员介绍系统。而成员可能是新的团队成员，或者是外部合作开发的分析师。 2. 用作涉众间的首要通信工具。这取决于涉众需要什么样的通信。下表给出了一些相关范例。 3. 作为系统分析的基础。为了支持分析工作，相关文档必须包含执行特定分析的必要信息。;表：相关文档和涉众通信需求; 文档涉众通常是系统文档或系统的既得利益者。因此，必须要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则，共有7条： 1.从读者的角度编写文档 2.避免出现不必要的重复 3.避免歧义 4.使用标准结构 5.记录基本原理 6.使文档保持更新，但频度不要过高 7.针对目标的适宜性对文档进行评审 这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。;规则1：从读者的角度编写文档 这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给你带来以下优势： 1. 面向读者编写的文档，通常总会赢得读者。 2. 面向读者编写文档是一种礼貌的表现。 3. 避免使用令人生厌的专业术语。 4. 容易使文档变得易读、易理解，提高文档的“效率”。对于专业读者，好的文档将有利于系统设计思想、代码等的理解。 文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。 意识流：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。 执行流：按软件执行时的思维顺序捕捉思维，并加以记录。 编制文档时，首先应该明确文档的每一节将要回答(或说明/记录)什么问题，并对自己的文档进行有效的组织。;规则4：使用标准结构 要点：标准结构有利于文档被更好的阅读和利用。 应该有计划的制定文档的标准结构方案，并确保文档的编制过程能够遵守，确保读者能够了解、理解。 标准结构文档至少具备以下优点： 能够帮助读者在文档中导航和快速查询特定信息。 2. 能够帮助文档编写者计划和组织内容，并透露那些带有“待定”标签的节，还有什么工作等待完成。 3. 可以方便表达文档各节需要表达的重要特征集，这样可以体现信息完整性规则。 具有标准结构的文档，其标准结构的另一个重要用途就是，能组成评审时文档验证的基础。;规则5：记录基本原理 要点：对基本原理进行记录可以节约大量的时间。 在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃的原因和理由。 这样的记录，或者是将来接受详细检查或被迫更改的需要，或者是为了以后可以重用设计。 通常在以下情况需要记录基本原理： 1. 在做出决策前，设计团队必须花费大量时间评估各种候选方案； 2. 决策对于某一需求或目标的实现很重要； 3. 初看似乎决策意义不明，但细察其背景信息后，决策变得逐渐明朗； 4. 在若干场合，有人向你提问：为什么这样做？ 5. 为团队新成员解惑； 6. 决策具有广泛影响，也难以消除这种影响； 7. 你认为，现在捕捉基本原理，比以后捕捉更加经济划算。;规则6：使文档保持更新，但频度不要过高 要点：人们总是乐意使用保持更新、内