- 1、本文档共17页,可阅读全部内容。
- 2、原创力文档(book118)网站文档一经付费(服务费),不意味着购买了该文档的版权,仅供个人/单位学习、研究之用,不得用于商业用途,未经授权,严禁复制、发行、汇编、翻译或者网络传播等,侵权必究。
- 3、本站所有内容均由合作方或网友上传,本站不对文档的完整性、权威性及其观点立场正确性做任何保证或承诺!文档内容仅供研究参考,付费前请自行鉴别。如您付费,意味着您自己接受本站规则且自行承担风险,本站不退款、不进行额外附加服务;查看《如何避免下载的几个坑》。如果您已付费下载过本站文档,您可以点击 这里二次下载。
- 4、如文档侵犯商业秘密、侵犯著作权、侵犯人身权等,请点击“版权申诉”(推荐),也可以打举报电话:400-050-0827(电话支持时间:9:00-18:30)。
查看更多
文档涉众通常是系统文档或系统的既得利益者。因此,必须要有一个基本规则,把良好的、可用的文档,与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则,共有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. 有时,为了使表达更为明确,或者在表达两个不
您可能关注的文档
- 软件工程第三讲需求分析(1).ppt
- 软件需求工程讲义第四讲需求分析(1).ppt
- 软件系统分析与设计3软件项目规划.ppt
- 软件工程第6章.ppt
- 输液风险及风险管理策略.ppt
- 辩证的否定观(新,详).ppt
- 辨析并修改病句歧义句.ppt
- 辨析并修改病句(修改).ppt
- 边际效用学派的经济学说11.ppt
- 辽宁省沈阳市第二十一中学高中英语Module2NoDrugsGrammar课件外研版必修2.ppt
- 江苏省灌云高级中学2023-2024学年高三上学期第一次月考地理试题含答案.docx
- 备战2024年高考物理一轮重难点复习 第十三章 近代物理.docx
- 江苏省高邮市一中2021-2022学年高三上学期第一次月考语文试题(原卷版).docx
- 江苏省华罗庚中学2023-2024学年高三上学期12月阶段检测数学试卷含答案.docx
- 江苏省海门中学2023-2024学年高三上学期第一次调研考试地理试题及答案.docx
- 备战2024年高考物理一轮重难点复习 第九章 恒定电流.docx
- 江苏省高邮市2023-2024学年高三下学期3月学情调研数学试题含答案.docx
- 备战2024年高考物理一轮重难点复习 实验十一:探究影响感应电流方向的因素.docx
- 备战2024年高考物理一轮重难点复习 实验三:验证平行四边形定则.docx
- 备战2024年高考物理一轮重难点复习 第十四章 光.docx
文档评论(0)