软件文档写作-第4讲文档表达(完整)课件.ppt

《软件文档写作-第4讲文档表达(完整)课件.ppt》由会员上传分享，免费在线阅读，更多相关内容在教育资源-天天文库。

1、第四讲软件文档表达诗歌是思想的疑聚，廖廖几行诗句能表极为复杂的思想。软件文档如何表达？24.1软件文档的编制原则1.适应文档涉众软件文档的涉众根据他们接触软件的角度、程度，对软件的需要、应用、操作等的不同，应有很大的不同。因此，文档作者在编制文档时，应深入了解文档涉众，特别注意自己编制的文档应适应特定读者的水平、特点和要求。2.应有必要的重复性国家标准关于14种软件文档的内容要求显然存在某些重复。较明显的有2类：即引言部分，每种文档都包含引言的内容，以向各类读者提供项目总的梗概；另一类是各种文

2、档的说明部分，如对功能性能的说明、对输入/输出的描述、系统配置环境等。这样，每种文档均可自成体系，单独提交给各自的读者，避免文档间的相互参阅，提高文档的阅读效率。3.应具有一定的灵活性鉴于软件项目开发过程的复杂性和灵活性，文档编制也应有一定的灵活性。34.2合理文档的7条规则软件文档必须能服务于各种用途。比如，它应该抽象到足以使新员工能迅速理解它；它应该详细到足以作为设计的蓝图；它应该包含足够的信息，以便作为分析和决策的基础。软件文档可能既是指示性文档，又是说明性文档。例如，对某些读者而言，它能

3、指示什么应该是正确的，并对决策的制定施加限制；对另一些读者而言，它能说明什么是正确的，并详述已经就系统设计作出的决策。因此，在对文档进行设计和评审的过程中，必须确保它能支持所有相关的需求。了解文档的用途是一件极为重要的事情，因为这些用途确定了文档的形式。通常，软件文档基本具有3种用途：用作教育工具。包括向成员介绍系统。而成员可能是新的团队成员，或者是外部合作开发的分析师。用作涉众间的首要通信工具。这取决于涉众需要什么样的通信。下表给出了一些相关范例。作为系统分析的基础。为了支持分析工作，相关文档

4、必须包含执行特定分析的必要信息。4涉众通信代表客户(群)的需求工程师和系统分析师就各种竞争性需求进行协商和权衡的论坛组成部分构架师和设计人员解决资源争端，并确定性能和其它运行时资源消费预算实现者为下游设计活动提供不能违背的限制和可利用的特权测试工程师和集成工程师为必须组合在一起的部件指定正确的黑盒行为维护工程师维护活动的起点，揭示预期更改会影响的区域必须和该系统进行交互的其他系统设计师确定打算提供和要求的操作集，及其操作协议管理人员组成开发团队的基础，这些团队分别对应已确认的工作任务、工作故障结

5、构、计划、项目资源分配和由各团队执行的进展跟踪产品线管理者确定产品家族中潜在的新成员是否处于范围之内，如果处于范围之内，距离多远质量保证小组一致性检验的基础，目的是确保实现方案取得系统要求的实际成果表：相关文档和涉众通信需求5文档涉众通常是系统文档或系统的既得利益者。要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则，共有7条：1.从读者的角度编写文档2.避免出现不必要的重复3.避免歧义4.使用标准结构5.记录基本原理6.使文档保持更新，但频度不要

6、过高7.针对目标的适宜性对文档进行评审这是一个区分良好的、可用的文档和有欠缺的、甚至是拙劣的文档的规则。规则1：从读者的角度编写文档这是一个浅显、重要，但总是被忽略的规则。然而，遵守该规则，会给你带来以下优势：面向读者编写的文档，通常总会赢得读者。面向读者编写文档是一种礼貌的表现。避免使用令人生厌的专业术语。容易使文档变得易读、易理解，提高文档的“效率”。对于专业读者，好的文档将有利于系统设计思想、代码等的理解。文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。意识流：按思维在编写者

7、头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。执行流：按软件执行时的思维顺序捕捉思维，并加以记录。编制文档时，首先应该明确文档的每一节将要回答(或说明/记录)什么问题，并对自己的文档进行有效的组织。规则2：避免出现不必要的重复要点：将每个信息都记录在确切的地方。如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读者心生疑问，影响文档的可理解性。但是，“避免不必要的重复”并不是机械的，必须墨守的成规。下列情况下

8、，有时还是可以有必要的信息重复：1.如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引用的位置非常重要。2.有时，为了使表达更为明确，或者在表达两个不同观点时，两个不同的视图可能会包含重复的信息。3.还有，就是为了保持文档的独立和自成体系，需要在同一文档体系的不同文档之间的各文档保留一定的重复信息。“避免不必要的重复”只是一个规则而已，而规则本身不能影响读者的理解。所以，有时以不同的形式表达相同的思想，只是为了有助于读者更透彻的理解，而不是对规则的违反。规则3：避免歧义要点：采用语义精确、