软件文档写作文档表达PPT课件

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