软件文档写作05-文档表达1

规则2：避免出现不必要的重复
要点：将每个信息都记录在确切的地方。 如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。
同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读 者心生疑问，影响文档的可理解性。
但是，“避免不必要的重复”并不是机械的，必须墨守的成规。下列情 况下，有时还是可以有必要的信息重复： 1. 如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引 用的位臵非常重要。 2. 有时，为了使表达更为明确，或者在表达两个不同观点时，两个不 同的视图可能会包含重复的信息。 3. 还有，就是为了保持文档的独立和自成体系，需要在同一文档体系 的不同文档之间的各文档保留一定的重复信息。 “避免不必要的重复”只是一个规则而已，而规则本身不能影响读者 的理解。所以，有时以不同的形式表达相同的思想，只是为了有助于读者更 透彻的理解，而不是对规则的违反。
第四章 软件文档表达
4.1 软件文档的编制原则
1ቤተ መጻሕፍቲ ባይዱ 适应文档涉众
软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、 操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了 解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。
2. 应有必要的重复性
国家标准关于14种软件文档的内容要求显然存在某些重复。较明显的有2 类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的 梗概；另一类是各种文档的说明部分，如对功能性能的说明、对输入/输出的 描述、系统配臵环境等。 这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的 相互参阅，提高文档的阅读效率。
文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。
意识流：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通 常缺乏可读的组织结构。
执行流：按软件执行时的思维顺序捕捉思维，并加以记录。 编制文档时，首先应该明确文档的每一节将要回答(或说明/记录)什么 问题，并对自己的文档进行有效的组织。
3. 清晰性：文档编制应力求简洁，并配有适当图、表，以增强其清晰性。
4. 完整性：同一文档体系中的任一文档都应是完整的、独立的，应能自成 体系。尽量减少不同文档之间的内容转引，以避免给读者带来不便。 5. 灵活性：能够根据各个不同项目的情况，决定编制文档的种类。并能根 据任务的规模、复杂性及项目开发和运行环境对文档的需求，判断确定文 档的详细程度。尤其是当相关标准所规定的文档种类无法满足应用需要时， 可以自行建立一些特殊的文档种类要求。
《软件产品开发文件编制指南》中，给出了一个例子，利用求和法， 综合衡量12种考虑因素，来确定应编制文档的种类。其具体过程见下表， 15 其中每一个因素给出一个分值，范围是1～5分。
√
√
√
√
维护和修改建议
产品市场宣传资料
√
√ √ √
14
4.5 文档编制的质量要求
为使软件文档能起到应有的作用，其编制工作必须保证质量。而高质 量的文档主要应该体现在以下几个方面： 1. 针对性：文档编制前先分清涉众对象。按不同类型、不同层次的读者， 决定如何编制相适应的文档。如管理文档和用户文档的编制就不应像开发 文档一样，使用过多的软件专用术语。 2. 精确性：文档的行为应十分确切，不能有多义性，不能有歧义。
规则5：记录基本原理
要点：对基本原理进行记录可以节约大量的时间。 在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃 的原因和理由。 这样的记录，或者是将来接受详细检查或被迫更改的需要，或者是为了 以后可以重用设计。 通常在以下情况需要记录基本原理： 1. 在做出决策前，设计团队必须花费大量时间评估各种候选方案； 2. 决策对于某一需求或目标的实现很重要；
规则7：针对目标的适宜性对文档进行评审 要点：评审是文档保持有效的前提。
文档的预期用户是文档是否以正确的方式展示其正确内容的最好的评判 者。应该寻求他们的帮助，在文档发布前，让文档所面向的预期用户(或代 表)对文档进行评审。
应该有有效的文档评审制度，以确保文档的质量和适用性。
4.3 文档表达的载体
3. 应具有一定的灵活性
鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活 性。
1
4.2 合理文档的7条规则
软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工 能迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息， 以便作为分析和决策的基础。 软件文档可能既是指示性文档，又是说明性文档。例如，对某些读者而 言，它能指示什么应该是正确的，并对决策的制定施加限制；对另一些读者 而言，它能说明什么是正确的，并详述已经就系统设计作出的决策。
标准结构文档至少具备以下优点：
1.能够帮助读者在文档中导航和快速查询特定信息。 2. 能够帮助文档编写者计划和组织内容，并透露那些带有 “待定”标签的节，还有什么工作等待完成。 3. 可以方便表达文档各节需要表达的重要特征集，这样可以 体现信息完整性规则。 具有标准结构的文档，其标准结构的另一个重要用途就 是，能组成评审时文档验证的基础。
规则3：避免歧义
要点：采用语义精确、定义明确的表示法。 通常，只要采用一组事先约定的表达，然后尽可能避免出现意外重复， 尤其是那些仅有“细微差别”的重复，就能有助于消除或避免歧义。 但是，形式语言并不是始终或总是需要的，因为还必须兼顾文档的可读 性、可理解性和可修改性。 应该尽量使文档读者确定或便于确定表示法的含义，除非双方默契。特 别是文档编制者引用其他地方定义的语义源，即使这个语义源是标准的或广 泛应用的语言，由于可能存在不同的版本，也应该使读者明确引用的具体版 本。
如果这样引用的一种表示法是用于内部开发的，就应该将其添加到内部 技术文档编制所采用的符号体系中去。
上述关于表示法引用的阐述，是避免歧义的一个良好的习惯。这样，既 能迫使你对系统各部分及其之间的关系加以了解，并能更为精准的表述，而 且，对读者也是一种周到的考虑和尊重。
规则4：使用标准结构 要点：标准结构有利于文档被更好的阅读和利用。 应该有计划的制定文档的标准结构方案，并确保文档的 编制过程能够遵守，确保读者能够了解、理解。
规则1：从读者的角度编写文档
这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给 你带来以下优势：
1. 面向读者编写的文档，通常总会赢得读者。
2. 面向读者编写文档是一种礼貌的表现。 3. 避免使用令人生厌的专业术语。
4. 容易使文档变得易读、易理解，提高文档的“效率”。对于专业读者， 好的文档将有利于系统设计思想、代码等的理解。
2. 自动文档：主要为方便读者阅读和传播，以电子文档的形式 存放于机器或其它如光盘、flash memory等载体上。自动文档 的形式主要有： 电子手册：如MS Word或Adobe Acrobat文档 超链接文档：是嵌入链接到网上的浏览用的文档格式 联机帮助：说明性的文本、图片、指导和嵌入在应用程序中的定义 多媒体操作导航系统：由声音、视频、文字等组成的系统操作指引 电子系统模型：格式化并存于系统的文本或图片格式，如GIF、JPEG 专用工具系统模型：用系统开发工具开发的模型，如集成开发环境、
3
文档涉众通常是系统文档或系统的既得利益者。 因此，必须要有一个基本规则，把良好的、可用的文 档，与那些拙劣的、缺乏考虑的文档区分开来。即所 谓合理文档的规则，共有7条： 1.从读者的角度编写文档 2.避免出现不必要的重复 3.避免歧义 4.使用标准结构 5.记录基本原理 6.使文档保持更新，但频度不要过高 7.针对目标的适宜性对文档进行评审 这是一个区分良好的、可用的文档和有欠缺的、 甚至是拙劣的文档的规则。
12
4.4 软件文档的涉众
软件文档涉众主要有以下几类：开发人员、维护人员、 管理人员、营销人员和用户。 具体的，上述各类涉众又可以再细分，如开发人员可 以细分为系统定义和分析工程师、系统架构师、系统设计 师、代码工程师、系统集成工程师、测试工程师…… 有不少软件文档的涉众，既是文档涉众，又是文档的 编制者。如系统构架师是系统需求规格说明书的涉众，但 同时他自己的工作成果又是通过编制系统构架文档来进行 传递。 我们这里所说的软件文档涉众，是指那些对某一类或 某种软件文档有特殊需求和期望的涉众。下表是各类文档 涉众以及他们需要的文档类型(部分)：
在最近20年里，软件文档的表达方式和载体有了很大的变 化。这些变化是由于技术的快速进步引起的。如上世纪80年代， 绝大多数的文档都被记载在纸质载体上，而现在的标准是自动 文档。然而，纸质文档并没有完全退出，很多情况下，纸质文 档甚至还是最重要的选择。 1. 纸质文档。主要用于保存那些可以(或需要)脱机阅读或 需要永久保存的文档资料，以及需要提交用户使用的资料。如 重要的项目定义、规划、设计、决策资料，结构复杂、规模较 大或在屏幕上阅读较不便的设计视图、流程图、表单等，用户 操作手册、培训资料等。 另外，还有许多文档资料尽管可以或已经制作成电子文档， 但由于永久保存的需要，它们仍然需要制作纸质文档存档。 还有一些文档因为安全保密的需要，也制作成纸质文档保 存，以尽可能减少外泄的可能。 11
13
开发人员 可行性研究报告 项目开发计划 软件需求说明书 数据要求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明书 模块开发卷宗 √ √ √ √ √ √ √ √ √
维护人员
管理人员 √ √
营销人员
用户 √ √ √
√ √ √ √ √
用户手册
操作手册 测试分析报告 开发进度月报 项目总结报告 √ √ √ √
DBMS和CASE工具等
实际应用中，可以将电子手册分布于一些标准的格式如 Adobe Acrobat和Windows帮助系统中，选择一种标准格式，以 便确保文档涉众能够用适当的软件查询所需文档。 而网页形式使得文档的改变变得十分的简单，因为只需更 新服务器上的文档，即可使全体有资格的涉众都能够获得同一 份新版的文档拷贝。