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

1、14.1 4.1 软件文档的编制原则软件文档的编制原则1. 1. 适应文档涉众适应文档涉众 软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。2. 2. 应有必要的重复性应有必要的重复性 国家标准关于国家标准关于1414种软件文档的内容要求显然存在某些重

2、复。较明显的有种软件文档的内容要求显然存在某些重复。较明显的有2 2类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的梗概；另一类是各种文档的说明部分，如对功能性能的说明、对输入梗概；另一类是各种文档的说明部分，如对功能性能的说明、对输入/ /输出的输出的描述、系统配置环境等。描述、系统配置环境等。 这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的相互参阅，提高文档的阅读效率。相互参阅，提高文档的阅读效率。3. 3. 应具有一定的灵活性应

3、具有一定的灵活性 鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活性。性。24.2 4.2 合理文档的合理文档的7 7条规则条规则 软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工能软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工能迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息，迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息，以便作为分析和决策的基础。以便作为分析和决策的基础。 软件文档可能既是软件文档可能既是指示性文档指示性文档，又是，又是说明性文档说明性文

4、档。例如，对某些读者而。例如，对某些读者而言，它能言，它能指示指示什么应该是正确的，并对决策的制定施加限制；对另一些读者什么应该是正确的，并对决策的制定施加限制；对另一些读者而言，它能而言，它能说明说明什么是正确的，并详述已经就系统设计作出的决策。什么是正确的，并详述已经就系统设计作出的决策。 因此，在对文档进行设计和评审的过程中，因此，在对文档进行设计和评审的过程中，必须确保必须确保它能支持所有相关它能支持所有相关的需求。的需求。 了解文档的用途是一件极为重要的事情，因为这些用途确定了文档的形了解文档的用途是一件极为重要的事情，因为这些用途确定了文档的形式。通常，软件文档基本具有式。通常，软

5、件文档基本具有3 3种用途：种用途：1. 1. 用作教育工具。包括向成员介绍系统。而成员可能是新的团队成员，或用作教育工具。包括向成员介绍系统。而成员可能是新的团队成员，或者是外部合作开发的分析师。者是外部合作开发的分析师。2. 2. 用作涉众间的首要通信工具。这取决于涉众需要什么样的通信。下表给用作涉众间的首要通信工具。这取决于涉众需要什么样的通信。下表给出了一些相关范例。出了一些相关范例。3. 3. 作为系统分析的基础。为了支持分析工作，相关文档必须包含执行特定作为系统分析的基础。为了支持分析工作，相关文档必须包含执行特定分析的必要信息。分析的必要信息。3表表：相关文档和涉众通信需求：相关

6、文档和涉众通信需求涉涉 众众通通 信信代表客户代表客户( (群群) )的需求工程师的需求工程师和系统分析师和系统分析师就各种竞争性需求进行协商和权衡的论坛就各种竞争性需求进行协商和权衡的论坛组成部分构架师和设计人员组成部分构架师和设计人员解决资源争端，并确定性能和其它运行时资源解决资源争端，并确定性能和其它运行时资源消费预算消费预算实现者实现者为下游设计活动提供不能违背的限制和可利用为下游设计活动提供不能违背的限制和可利用的特权的特权测试工程师和集成工程师测试工程师和集成工程师为必须组合在一起的部件指定正确的黑盒行为为必须组合在一起的部件指定正确的黑盒行为维护工程师维护工程师维护活动的起点，揭

7、示预期更改会影响的区域维护活动的起点，揭示预期更改会影响的区域必须和该系统进行交互的其必须和该系统进行交互的其他系统设计师他系统设计师确定打算提供和要求的操作集，及其操作协议确定打算提供和要求的操作集，及其操作协议管理人员管理人员组成开发团队的基础，这些团队分别对应已确组成开发团队的基础，这些团队分别对应已确认的工作任务、工作故障结构、计划、项目资认的工作任务、工作故障结构、计划、项目资源分配和由各团队执行的进展跟踪源分配和由各团队执行的进展跟踪产品线管理者产品线管理者确定产品家族中潜在的新成员是否处于范围之确定产品家族中潜在的新成员是否处于范围之内，如果处于范围之内，距离多远内，如果处于范围

8、之内，距离多远质量保证小组质量保证小组一致性检验的基础，目的是确保实现方案取得一致性检验的基础，目的是确保实现方案取得系统要求的实际成果系统要求的实际成果4 文档涉众通常是系统文档或系统的既得利益者。文档涉众通常是系统文档或系统的既得利益者。因此，必须要有一个基本规则，把良好的、可用的文因此，必须要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓谓合理文档的规则合理文档的规则，共有，共有7 7条：条： 1.1.从读者的角度编写文档从读者的角度编写文档 2.2.避免出现不必要的重复避免出现不必要的重复 3.3.避免歧

9、义避免歧义 4.4.使用标准结构使用标准结构 5.5.记录基本原理记录基本原理 6.6.使文档保持更新，但频度不要过高使文档保持更新，但频度不要过高 7.7.针对目标的适宜性对文档进行评审针对目标的适宜性对文档进行评审这是一个区分良好的、可用的文档和有欠缺的、这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。甚至是拙劣的文档的规则。5规则规则1 1：从读者的角度编写文档：从读者的角度编写文档 这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给你带来以下优势：你带来以下优势：1. 1. 面向读者编写的文档，

10、通常总会赢得读者。面向读者编写的文档，通常总会赢得读者。2. 2. 面向读者编写文档是一种礼貌的表现。面向读者编写文档是一种礼貌的表现。3. 3. 避免使用令人生厌的专业术语。避免使用令人生厌的专业术语。4. 4. 容易使文档变得易读、易理解，提高文档的容易使文档变得易读、易理解，提高文档的“效率效率”。对于专业读者，。对于专业读者，好的文档将有利于系统设计思想、代码等的理解。好的文档将有利于系统设计思想、代码等的理解。 文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。 意识流意识流：按思维在编写者头脑中出现的顺序捕捉思维

11、，并加以记录。通：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。常缺乏可读的组织结构。 执行流执行流：按软件执行时的思维顺序捕捉思维，并加以记录。：按软件执行时的思维顺序捕捉思维，并加以记录。 编制文档时，首先应该明确文档的每一节将要回答编制文档时，首先应该明确文档的每一节将要回答( (或说明或说明/ /记录记录) )什么什么问题，并对自己的文档进行有效的组织。问题，并对自己的文档进行有效的组织。6规则规则2 2：避免出现不必要的重复避免出现不必要的重复 要点要点：将每个信息都记录在确切的地方。将每个信息都记录在确切的地方。 如此，可使文档更便于理解和使用，在需要

12、演化时，也能更便于修改。如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。 同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读者心生疑问，影响文档的可理解性。者心生疑问，影响文档的可理解性。 但是，但是，“避免不必要的重复避免不必要的重复”并不是机械的，必须墨守的成规。下列情并不是机械的，必须墨守的成规。下列情况下，有时还是可以有必要的信息重复：况下，有时还是可以有必要的信息重复： 1. 1. 如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引用的

13、位置非常重要。用的位置非常重要。 2. 2. 有时，为了使表达更为明确，或者在表达两个不同观点时，两个不有时，为了使表达更为明确，或者在表达两个不同观点时，两个不同的视图可能会包含重复的信息。同的视图可能会包含重复的信息。 3. 3. 还有，就是为了保持文档的独立和自成体系，需要在同一文档体系还有，就是为了保持文档的独立和自成体系，需要在同一文档体系的不同文档之间的各文档保留一定的重复信息。的不同文档之间的各文档保留一定的重复信息。 “ “避免不必要的重复避免不必要的重复”只是一个规则而已，而规则本身不能影响读者只是一个规则而已，而规则本身不能影响读者的理解。所以，有时以不同的形式表达相同的思

14、想，只是为了有助于读者更的理解。所以，有时以不同的形式表达相同的思想，只是为了有助于读者更透彻的理解，而不是对规则的违反。透彻的理解，而不是对规则的违反。7规则规则3 3：避免歧义避免歧义 要点要点：采用语义精确、定义明确的表示法。采用语义精确、定义明确的表示法。 通常，只要采用一组事先约定的表达，然后尽可能避免出现意外重复，通常，只要采用一组事先约定的表达，然后尽可能避免出现意外重复，尤其是那些仅有尤其是那些仅有“细微差别细微差别”的重复，就能有助于消除或避免歧义。的重复，就能有助于消除或避免歧义。 但是，形式语言并不是始终或总是需要的，因为还必须兼顾文档的可读但是，形式语言并不是始终或总是

15、需要的，因为还必须兼顾文档的可读性、可理解性和可修改性。性、可理解性和可修改性。 应该尽量使文档读者确定或便于确定表示法的含义，除非双方默契。特应该尽量使文档读者确定或便于确定表示法的含义，除非双方默契。特别是文档编制者引用其他地方定义的语义源，即使这个语义源是标准的或广别是文档编制者引用其他地方定义的语义源，即使这个语义源是标准的或广泛应用的语言，由于可能存在不同的版本，也应该使读者明确引用的具体版泛应用的语言，由于可能存在不同的版本，也应该使读者明确引用的具体版本。本。 如果这样引用的一种表示法是用于内部开发的，就应该将其添加到内部如果这样引用的一种表示法是用于内部开发的，就应该将其添加到

16、内部技术文档编制所采用的符号体系中去。技术文档编制所采用的符号体系中去。 上述关于表示法引用的阐述，是避免歧义的一个良好的习惯。这样，既上述关于表示法引用的阐述，是避免歧义的一个良好的习惯。这样，既能迫使你对系统各部分及其之间的关系加以了解，并能更为精准的表述，而能迫使你对系统各部分及其之间的关系加以了解，并能更为精准的表述，而且，对读者也是一种周到的考虑和尊重。且，对读者也是一种周到的考虑和尊重。8规则规则4 4：使用标准结构使用标准结构 要点要点：标准结构有利于文档被更好的阅读和利用。标准结构有利于文档被更好的阅读和利用。 应该有计划的制定文档的标准结构方案，并确保文档的应该有计划的制定文

17、档的标准结构方案，并确保文档的编制过程能够遵守，确保读者能够了解、理解。编制过程能够遵守，确保读者能够了解、理解。 标准结构文档至少具备以下优点：标准结构文档至少具备以下优点：能够帮助读者在文档中导航和快速查询特定信息。能够帮助读者在文档中导航和快速查询特定信息。2. 2. 能够帮助文档编写者计划和组织内容，并透露那些带有能够帮助文档编写者计划和组织内容，并透露那些带有“待定待定”标签的节，还有什么工作等待完成。标签的节，还有什么工作等待完成。3. 3. 可以方便表达文档各节需要表达的重要特征集，这样可以可以方便表达文档各节需要表达的重要特征集，这样可以体现信息完整性规则。体现信息完整性规则。

18、1.1. 具有标准结构的文档，其标准结构的另一个重要用途具有标准结构的文档，其标准结构的另一个重要用途就是，能组成评审时文档验证的基础。就是，能组成评审时文档验证的基础。9规则规则5 5：记录基本原理记录基本原理 要点要点：对基本原理进行记录可以节约大量的时间。对基本原理进行记录可以节约大量的时间。 在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃的原因和理由。的原因和理由。 这样的记录，或者是将来接受详细检查或被迫更改的需要，或者是为了这样的记录，或者是将来接受详细检查或被迫更改的需要，或者是为了以后可以重用设计。以

19、后可以重用设计。 通常在以下情况需要记录基本原理：通常在以下情况需要记录基本原理：1. 1. 在做出决策前，设计团队必须花费大量时间评估各种候选方案；在做出决策前，设计团队必须花费大量时间评估各种候选方案；2. 2. 决策对于某一需求或目标的实现很重要；决策对于某一需求或目标的实现很重要；3. 3. 初看似乎决策意义不明，但细察其背景信息后，决策变得逐渐明朗；初看似乎决策意义不明，但细察其背景信息后，决策变得逐渐明朗；4. 4. 在若干场合，有人向你提问：为什么这样做？在若干场合，有人向你提问：为什么这样做？5. 5. 为团队新成员解惑；为团队新成员解惑；6. 6. 决策具有广泛影响，也难以消

20、除这种影响；决策具有广泛影响，也难以消除这种影响；7. 7. 你认为，现在捕捉基本原理，比以后捕捉更加经济划算。你认为，现在捕捉基本原理，比以后捕捉更加经济划算。10规则规则6 6：使文档保持更新，但频度不要过高使文档保持更新，但频度不要过高 要点要点：人们总是乐意使用保持更新、内容精准的文档。人们总是乐意使用保持更新、内容精准的文档。 软件文档应该是该软件最终、最权威的信息源。通过引用合适的文档，软件文档应该是该软件最终、最权威的信息源。通过引用合适的文档，我们能够最为容易、最为有效地回答关于该软件的问题。我们能够最为容易、最为有效地回答关于该软件的问题。 然而，文档的更新却没有必要为那些无

21、法持久的决策做出反映。这样做，然而，文档的更新却没有必要为那些无法持久的决策做出反映。这样做，其实是一种高成本和浪费资源的愚笨做法。其实是一种高成本和浪费资源的愚笨做法。 事实上，应该在开发计划中指定文档更新的特定内容或过程，使文档服事实上，应该在开发计划中指定文档更新的特定内容或过程，使文档服从版本控制，并制定一项文档发布策略，使得文档具有更好的服务特性。从版本控制，并制定一项文档发布策略，使得文档具有更好的服务特性。规则规则7 7：针对目标的适宜性对文档进行评审针对目标的适宜性对文档进行评审 要点要点：评审是文档保持有效的前提。评审是文档保持有效的前提。 文档的预期用户是文档是否以正确的方

22、式展示其正确内容的最好的评判文档的预期用户是文档是否以正确的方式展示其正确内容的最好的评判者。应该寻求他们的帮助，在文档发布前，让文档所面向的预期用户者。应该寻求他们的帮助，在文档发布前，让文档所面向的预期用户( (或代或代表表) )对文档进行评审。对文档进行评审。 应该有有效的文档评审制度，以确保文档的质量和适用性。应该有有效的文档评审制度，以确保文档的质量和适用性。114.3 4.3 文档表达的载体文档表达的载体 在最近在最近2020年里，软件文档的表达方式和载体有了很大的变年里，软件文档的表达方式和载体有了很大的变化。这些变化是由于技术的快速进步引起的。如上世纪化。这些变化是由于技术的快

23、速进步引起的。如上世纪8080年代，年代，绝大多数的文档都被记载在纸质载体上，而现在的标准是自动绝大多数的文档都被记载在纸质载体上，而现在的标准是自动文档。然而，纸质文档并没有完全退出，很多情况下，纸质文文档。然而，纸质文档并没有完全退出，很多情况下，纸质文档甚至还是最重要的选择。档甚至还是最重要的选择。 1. 1. 纸质文档纸质文档。主要用于保存那些可以。主要用于保存那些可以( (或需要或需要) )脱机阅读或脱机阅读或需要永久保存的文档资料，以及需要提交用户使用的资料。如需要永久保存的文档资料，以及需要提交用户使用的资料。如重要的项目定义、规划、设计、决策资料，结构复杂、规模较重要的项目定义

24、、规划、设计、决策资料，结构复杂、规模较大或在屏幕上阅读较不便的设计视图、流程图、表单等，用户大或在屏幕上阅读较不便的设计视图、流程图、表单等，用户操作手册、培训资料等。操作手册、培训资料等。 另外，还有许多文档资料尽管可以或已经制作成电子文档，另外，还有许多文档资料尽管可以或已经制作成电子文档，但由于永久保存的需要，它们仍然需要制作纸质文档存档。但由于永久保存的需要，它们仍然需要制作纸质文档存档。 还有一些文档因为安全保密的需要，也制作成纸质文档保还有一些文档因为安全保密的需要，也制作成纸质文档保存，以尽可能减少外泄的可能。存，以尽可能减少外泄的可能。122. 2. 自动文档自动文档：主要为

25、方便读者阅读和传播，以电子文档的形式：主要为方便读者阅读和传播，以电子文档的形式存放于机器或其它如光盘、存放于机器或其它如光盘、flash memoryflash memory等载体上。自动文档等载体上。自动文档的形式主要有：的形式主要有： 电子手册电子手册：如如MS WordMS Word或或Adobe AcrobatAdobe Acrobat文档文档 超链接文档超链接文档：是嵌入链接到网上的是嵌入链接到网上的浏览用的文档格式浏览用的文档格式 联机帮助联机帮助：说明性的文本、图片、指导和嵌入在应用程序中的定义说明性的文本、图片、指导和嵌入在应用程序中的定义 多媒体操作导航系统多媒体操作导航系

26、统：由声音、视频、文字等组成的系统操作指引由声音、视频、文字等组成的系统操作指引 电子系统模型电子系统模型：格式化并存于系统的文本或图片格式，如格式化并存于系统的文本或图片格式，如GIFGIF、JPEGJPEG 专用工具系统模型专用工具系统模型：用系统开发工具开发的模型，如集成开发环境、用系统开发工具开发的模型，如集成开发环境、DBMSDBMS和和CASECASE工具等工具等 实际应用中，可以将电子手册分布于一些标准的格式如实际应用中，可以将电子手册分布于一些标准的格式如Adobe AcrobatAdobe Acrobat和和WindowsWindows帮助系统中，选择一种标准格式，以帮助系统

27、中，选择一种标准格式，以便确保文档涉众能够用适当的软件查询所需文档。便确保文档涉众能够用适当的软件查询所需文档。 而网页形式使得文档的改变变得十分的简单，因为只需更而网页形式使得文档的改变变得十分的简单，因为只需更新服务器上的文档，即可使全体有资格的涉众都能够获得同一新服务器上的文档，即可使全体有资格的涉众都能够获得同一份新版的文档拷贝。份新版的文档拷贝。134.4 4.4 软件文档的涉众软件文档的涉众 软件文档涉众主要有以下几类：开发人员、维护人员、软件文档涉众主要有以下几类：开发人员、维护人员、管理人员、营销人员和用户。管理人员、营销人员和用户。 具体的，上述各类涉众又可以再细分，如开发人

28、员可具体的，上述各类涉众又可以再细分，如开发人员可以细分为系统定义和分析工程师、系统架构师、系统设计以细分为系统定义和分析工程师、系统架构师、系统设计师、代码工程师、系统集成工程师、测试工程师师、代码工程师、系统集成工程师、测试工程师 有不少软件文档的涉众，既是文档涉众，又是文档的有不少软件文档的涉众，既是文档涉众，又是文档的编制者。如系统构架师是系统需求规格说明书的涉众，但编制者。如系统构架师是系统需求规格说明书的涉众，但同时他自己的工作成果又是通过编制系统构架文档来进行同时他自己的工作成果又是通过编制系统构架文档来进行传递。传递。 我们这里所说的软件文档涉众，是指那些对某一类或我们这里所说

29、的软件文档涉众，是指那些对某一类或某种软件文档有特殊需求和期望的涉众。下表是各类文档某种软件文档有特殊需求和期望的涉众。下表是各类文档涉众以及他们需要的文档类型涉众以及他们需要的文档类型( (部分部分) )：14开发人员开发人员维护人员维护人员管理人员管理人员营销人员营销人员用户用户可行性研究报告可行性研究报告项目开发计划项目开发计划软件需求说明书软件需求说明书数据要求说明书数据要求说明书测试计划测试计划概要设计说明书概要设计说明书详细设计说明书详细设计说明书数据库设计说明书数据库设计说明书模块开发卷宗模块开发卷宗用户手册用户手册操作手册操作手册测试分析报告测试分析报告开发进度月报开发进度月报

30、项目总结报告项目总结报告维护和修改建议维护和修改建议产品市场宣传资料产品市场宣传资料154.5 4.5 文档编制的质量要求文档编制的质量要求 为使软件文档能起到应有的作用，其编制工作必须保证质量。而高质为使软件文档能起到应有的作用，其编制工作必须保证质量。而高质量的文档主要应该体现在以下几个方面：量的文档主要应该体现在以下几个方面：1. 1. 针对性针对性：文档编制前先分清涉众对象。按不同类型、不同层次的读者，：文档编制前先分清涉众对象。按不同类型、不同层次的读者，决定如何编制相适应的文档。如管理文档和用户文档的编制就不应像开发决定如何编制相适应的文档。如管理文档和用户文档的编制就不应像开发文

31、档一样，使用过多的软件专用术语。文档一样，使用过多的软件专用术语。2. 2. 精确性精确性：文档的行为应十分确切，不能有多义性，不能有歧义。：文档的行为应十分确切，不能有多义性，不能有歧义。3. 3. 清晰性清晰性：文档编制应力求简洁，并配有适当图、表，以增强其清晰性。：文档编制应力求简洁，并配有适当图、表，以增强其清晰性。4. 4. 完整性完整性：同一文档体系中的任一文档都应是完整的、独立的，应能自成：同一文档体系中的任一文档都应是完整的、独立的，应能自成体系。尽量减少不同文档之间的内容转引，以避免给读者带来不便。体系。尽量减少不同文档之间的内容转引，以避免给读者带来不便。5. 5. 灵活性

32、灵活性：能够根据各个不同项目的情况，决定编制文档的种类。并能根：能够根据各个不同项目的情况，决定编制文档的种类。并能根据任务的规模、复杂性及项目开发和运行环境对文档的需求，判断确定文据任务的规模、复杂性及项目开发和运行环境对文档的需求，判断确定文档的详细程度。尤其是当相关标准所规定的文档种类无法满足应用需要时，档的详细程度。尤其是当相关标准所规定的文档种类无法满足应用需要时，可以自行建立一些特殊的文档种类要求。可以自行建立一些特殊的文档种类要求。 软件产品开发文件编制指南软件产品开发文件编制指南中，给出了一个例子，利用求和法，中，给出了一个例子，利用求和法，综合衡量综合衡量1212种考虑因素，来确定应编制文档的种类。其具体过程见下表，种考虑因素，来确定应编制文档的种类。其