1、01 正确理解文档,02 文档编写的三个步骤,03 文档编排管理,软件（英文：Software）是一系列按照特定顺序组织的计算机数据和指令的集合。一般来讲软件被划分为系统软件、应用软件和介于这两者之间的中间件。软件并不只是包括可以在计算机（这里的计算机是指广义的计算机）上运行的电脑程序，与这些电脑程序相关的文档一般也被认为是软件的一部分。简单的说软件就是程序加文档的集合体。另也泛指社会结构中的管理系统、思想意识形态、思想政治觉悟、法律法规等等。,1.1.1 什么是软件？,第一节 软件文档概念,1.1.2 为什么需要软件文档？,第一节 软件文档概念,项目管理的依据：文档将通常“不可见的”软件开发
2、进程转换成“可见的”文字资料，有利于项目的管理。 技术交流的语言：项目小组内部、项目平行开发的各小组之间进行的交流和联系，通常都是通过文档来实现的。 项目质量保证：文档是进行项目质量审查和评价的重要依据，有效文档的提供，可以满足项目质量保证人员和审查人员的工作需要。 支持培训与维护：合格的软件文档通常都提供有关软件运行、维护和培训的必要信息，支持软件产品的应用。 支持软件维护：软件文档提供系统开发的全部必要技术资料，有利于维护人员熟悉系统，开展维护工作；软件维护文档记载了软件维护过程中软件及其环境变化的全部信息。 记载软件历史： 软件文档作为“记载软件历史的语言”，可用作未来项目的一种资源，向
3、潜在用户报道软件的各种有利信息，便于他们判断自己是否需要该软件提供的服务。,第一节 软件文档概念,1.1.3 文档的作用,第二节 软件文档分类,1.2.1 根据产生和使用范围分,软件文档,开发文档,用户文档,管理文档, 可行性研究报告 项目开发计划 软件需求说明书, 数据库设计说明书 概要设计说明书 详细设计说明书, 用户手册 操作手册, 软件需求说明书 数据要求说明书, 项目开发计划 开发进度月报 测试计划, 测试分析报告 项目开发总结报告,1.2.2 开发文档,开发文档主要可以发挥以下几个方面的作用： 作为软件生存期整个阶段之间的通信工具，记录生成软件需求、设计、编码、测试等的详细规定和说
4、明； 描述开发小组的工作职责。通过规定软件规划设计、主题事项、文档编制、质量保证等人员的角色，来定义“如何做”和“何时做”； 用作检验点，而允许管理者评估开发进度。如果开发文档缺失或过时，管理者将失去跟踪和控制软件项目的重要工具； 形成系统维护人员所要求的基本的软件支持文档，并构成产品文档 的一部分； 记录软件开发的历史。,开发文档主要负责对软件开发过程进行描述和规范。开发文档除了前面列表的内容，还包括软件的详细技术描述，如程序逻辑、程序间相互关系、数据格式、存储等。,第二节 软件文档分类,1.2.3 用户文档,用户文档主要发挥以下作用： 为使用和运行软件产品的用户提供培训和运行参考信息； 为
5、产品维护工程师提供必要的信息； 促进和方便软件产品的市场推广。,用户文档主要负责对软件产品的安装、配置、使用、维护等信息进行描述。包括系统安装配置手册、用户操作手册、软件需求说明书、数据要求说明书等。,第二节 软件文档分类,1.2.4 管理文档,管理文档主要有以下作用： 软件初期定义、规划、商务等与客户互动结果的记录； 开发过程每个阶段的进度和进度变更的记录； 软件开发人员的组织、管理和变更的记录； 软件需求、规划、设计等的变更控制的记录； 开发过程发生的各种审查、审核、评估等情况的记录； 验收、培训、移交、安装等相关工作的实施记录； 维护需求的提出、认定、计划、实施等工作的记录。,管理文档主
6、要是对软件开发过程的管理信息进行描述。管理文档除了前面列表内容，还应该包括被管理者的反馈信息，如各色表格、工作总结、开发体会、产品建议等。,第二节 软件文档分类,软件文档最终需要回答读者关心的下列问题：,第三节 软件文档最终需要回答的问题,01 正确理解文档,02 文档编写的三个步骤,03 文档编排管理,那么，软件文档如何表达？。,第一节 引言,2.1.1 诗歌与编码,第一节 引言,2.1.2 知其然,通常版本的故事是这样的,第一节 引言,2.1.3 知其所以然,高手的故事是这样的,步骤分解说明,文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。意识流：按思维在编写者头脑中出现的顺序
7、捕捉思维，并加以记录。通常缺乏可读的组织结构。执行流：按软件执行时的思维顺序捕捉思维，并加以记录。缺乏重点内容的突出展现。,写给谁看？ 写什么？ 需要达到什么效果？ ,用什么顺序？ 是否需要拆分文档？ 能否说明问题？ ,是否抓住重点？ 是否有重复？ 是否有歧义？ ,第二节 文档编写的三个步骤,2.2.1 步骤分解,2.2.2 文档涉众对像对照,第二节 文档编写的三个步骤,2.2.3 文档内容编写对照,第二节 文档编写的三个步骤,在开始软件文档编写前，首先要考虑的是:如何对文档内容进行组织?由于软件系统的特殊性,其内容表达的组织方式也有自己独特的如下几种可选择的方式：,就是文档的编制大纲。反映文
8、档组织构架的“初步设计内容表” 把收集的材料归类。,介绍文档的核心内容和主题思想及文档的组织结构等，一般300500字为宜。,按重要性的顺序。如培训资料等的绪论 按由简及繁的顺序。如用户手册文档 按时间/软件的运行顺序。一般的步骤说明要用此方式 分析法。把复杂问题分解为若干个主要问题进行说明，如文档的绪论部分 专题法。如按功能分类组织内容,2.2.4 软件文档的内容组织,第二节 文档编写的三个步骤,01,直叙式,02,编号指教式,03,剧本式,04,四步法,2.2.5 选择文档写作表达方式,第二节 文档编写的三个步骤,编制软件文档时，应该根据不同文档的性质、类型以及涉众的类型、专业能力等，在确
9、定文档编制计划、内容和步骤后，还要确定文档编制的表达方法。需要编入文档的资料以怎样的方式表达，对该文档涉众以及软件产品、文档等的传播有很大的影响。,点击“取消确认”按钮取消确认账单，账单状态由已确认改为未确认。需校验当前用户角色所属组织的结算公司是否与账单的结算公司一致，若不一致，不允许取消确认。提示用户：当前用户角色所属组织的结算公司是否与账单的结算公司不一致，不允许取消确认。还需校验账单是否已被合并，若已合并，提示用户：账单已合并，不允许取消确认。若当前用户角色所属结算公司的办事处配置要求必须做账单，则还需校验账单是否含有已开票或部分开票、已请款或部分请款、已核销或部分核销的费用。若含有已
10、开票或部分开票的费用，提示用户：账单含有已开票或部分开票的费用，不允许取消确认。若含有已请款或部分请款的费用，提示用户：账单含有已请款或部分请款的费用，不允许取消确认。若含有已核销或部分核销的费用，提示用户：账单含有已核销或部分核销的费用，不允许取消确认。,例子,要点：,注意这种方式会使某些信息在段落中丢失。,1,第二节 文档编写的三个步骤,2.2.6 直叙式,按照文档中上下文关系，平铺直叙需要编入文档的内容。这是多数文档常用的表达形式。下图是一个直叙式编档的例：,2. 取消确认账单2.1 用户点击“取消确认”按钮2.2 系统校验当前用户角色所属组织的结算公司是否与账单的结算公司一致，若不一致
11、，不允许取消确认并提示用户：当前用户角色所属组织的结算公司是否与账单的结算公司不一致，不允许取消确认。2.3 系统校验账单是否已合并，若已合并，提示用户：账单已合并，不允许取消确认。2.4 系统校验账单是否含有“已开票”或“部分开票”的费用，如果有则提示用户：账单含有已开票或部分开票的费用，不允许取消确认。2.5 系统校验账单是否含有“已请款”或“部分请款”的费用，如果有则提示用户：账单含有已请款或部分请款的费用，不允许取消确认。2.6 系统校验账单是否含有“已核销”或“部分核销”的费用，如果有则提示用户：账单含有已核销或部分核销的费用，不允许取消确认。2.7 如果校验通过，系统更改账单状态由
12、“已确认”改为“未确认”。,例子,要点：,这种表达方式使需要完成的工作十分明确，且数据的长度、格式也有规定，尽管占用的空间稍大，但阅读方便，能使读者快速找到需要的内容。,2,第二节 文档编写的三个步骤,2.2.7 编号指教式,以菜谱式为基础，将文档中描述的软件工作步骤或处理过程加以编号，其表达结果会比直叙式更适合阅读理解。,订购员： 1. 完成订购输入单(P0123)a. 订购号：预先印在单据上的顺序号b. 日期：输入当前日期。采用yyyymmdd的8位表达，如将2005年12月1日表示为20051201c. 供货企业：输入接受订货的企业名。最多25个汉字d. 货号：输入要订购的货号。在库存清
13、单中找货号。若为新增，则见新增货物部分 操作员： 2. 将订购单输入计算机 系统员： 3. 数据录入计算机，并更新订购文件,例子,要点：,剧本式会比编号指教式占用更多的篇幅，直叙法使文档内容泛而无重点，编号指教法则突出执行者即角色的作用欠缺。而剧本法者使角色的任务十分鲜明，不同用户只需阅读相关部分即可。,3,第二节 文档编写的三个步骤,2.2.8 剧本式,将文档以剧本方式表达。也有“演员”，以及动作。下图是这种方法的例：,提单打印命令利用打印命令，可得到提单的纸质拷贝。在一页纸上的打印宽度和纸的宽度有关。通过指定上、下边缘及打印长度和宽度，可修改提单边缘的设定。打印表格的一般步骤：1. 务必连
14、接好打印机，装好打印纸并打开电源2. 按P键3. 如果提单预定的边缘可接受RETURN键，开始打印表格4. 如果希望改变边缘，按M键，可得到边缘修改子命令。屏幕显示提单预先设定的边缘参数。使用TAB键，把光标移到要修改的边缘处，输入新的的边缘值，按RETURN键5. 完成第4步后，仍然处在打印命令状态。按RETURN键，开始打印表格 例如，当在打印命令状态中按M键时，显示提单的预设边缘值：边缘： 左：6 上：8 宽：72长：60 纸长：66,例子,要点：,四步法将比直叙式能更有效的提供这样的指导： 动机或理由。用户需要做什么？为什么要做？ 效果。当用户操作之后，会发生什么？ 一般步骤。为实现所
15、要的效果，典型的操作步骤是什么？ 范例。操作和执行结果的例子,4,第二节 文档编写的三个步骤,2.2.9 四步法,即使有几种用户使用软件包，但无法知道谁需要做什么。并且，系统操作过程也不一定是一步接一步，而是需要用户判断接下去做什么，及何时做。对此种情形，唯有直叙式表达和所谓的四步法适用。因为用户手册需要提供用户何时及为什么执行某项功能的指导。,1.从读者的角度编写文档,2.避免出现不必要的重复,3.避免歧义,4.使用标准结构。,要有一个基本规则，把良好的、可用的文档，与那些拙劣的、缺乏考虑的文档区分开来。即所谓合理文档的规则，共有7条：,第三节 合理文档的7条规则,5.记录基本原理,6.使文
16、档保持更新，但频度不要过高,7.针对目标的适宜性对文档进行评审,例子,1,问题：,没有从客户的角度考虑他们最关注什么？,第三节 合理文档的7条规则,系统性能要求 1、可靠性要求：在现有的软硬件以及网络环境条件下，系统能支持40个并发用户多功能同时在线操作，单表500万条记录正常进行业务功能操作； 2、性能响应要求：在网络现有条件和连通正常的情况下，应用系统对操作较频繁的常用业务处理的响应时间必须足够快。系统满足至少3年业务管理数据存储环境的运行要求。在满足至少3年业务数据量的情况下： 单条业务处理的界面显示时间低于5秒钟； 若网络连通正常，一般性数据保存、修改、删除等操作的响应反馈速度最多不应
17、超过3秒，一般控制在1-2秒； 一般1万条数据的简单查询不应超过5秒，十万条数据的查询不应超过30秒。复杂综合性跨模块查询不超过1分钟； 日常报表产生时间应低于10秒2分钟（视报表复杂程度）。,例子,问题：,描述不够准确，细化。,2,第三节 合理文档的7条规则,用户看完一叠厚厚的需求文档后，觉得很迷茫，好像文档所叙述的内容没有问题，但对根据文档开发出来的软件是否是自己需要的没有把握，拒绝签字,开发人员总是反映需要文档不够细致，不能体现到每个按钮、每个字段的要求；一些熟练的开发人员希望每个迭代的文档更有针对性，如果每个迭代的需求文档都是在之前的需求文档上叠加，那么他们需要花费很长时间把那些修改之
18、处找出来.,文档的受众无法获取其关注的内容。,第三节 合理文档的7条规则,2.3.1 文档编写存在问题,心中有读者,明确目标读者,利用文档模板,规范用词,进行版本管理,为每个文档或每段文字都要有明确的目标读者。软件文档的读者往往很多，用户、客户、分析、开发等，每个角色看文档的目的是不一样的，因此他们各自对文档的要求也是不一样的。从“为读者着想”的指导思想出发，高质量的文档，需要让读者一眼就能明白哪些是他关心的内容。,利用文档模板，但不要被模板束缚，模板可以根据项目实际情况进行裁减，避免出现没什么可写，但又必须填些内容。,文艺作品讲究重复强调主题，但又需要用很多不同的近义词来突显主题，而作为技术
19、文档，同义词只会引起敏感人员的疑惑，如“编辑”、“修改”、“更改”；用好词汇表，词汇表是一个规范用词的做法，也是对一些专有名词的解释，不仅仅局限于专用名词，可以推广到动词和句式。,个版本，这个版本能给任何人员以足够信息；二是能够快速定位某年某月的某个版本究竟有哪些改动，改动之前是怎么样的，改动之后又是怎样的。用好Word的审阅（Track)功能。,第三节 合理文档的7条规则,2.3.2 从读者的角度编写文档,要点：将每个信息都记录在确切的地方。,如此，可使文档更便于理解和使用，在需要演化时，也能更便于修改。同时，这一方法还能避免产生混乱。有时，重复信息的细微差别会使读者心生疑问，影响文档的可理
20、解性。 “避免不必要的重复”只是一个规则而已，而规则本身不能影响读者的理解。所以，有时以不同的形式表达相同的思想，只是为了有助于读者更透彻的理解，而不是对规则的违反。,但是，“避免不必要的重复”并不是机械的，必须墨守的成规。下列情况下，有时还是可以有必要的信息重复：1. 如果，过多的不必要的翻页，可能会使读者生厌。因此，信息引用的位置非常重要。2. 有时，为了使表达更为明确，或者在表达两个不同观点时，两个不同的视图可能会包含重复的信息。3. 还有，就是为了保持文档的独立和自成体系，需要在同一文档体系的不同文档之间的各文档保留一定的重复信息。,第三节 合理文档的7条规则,2.3.3 避免不必要的
21、重复,要点：采用语义精确、定义明确的表示法。,通常，只要采用一组事先约定的表达，然后尽可能避免出现意外重复，尤其是那些仅有“细微差别”的重复，就能有助于消除或避免歧义。但是，形式语言并不是始终或总是需要的，因为还必须兼顾文档的可读性、可理解性和可修改性。,应该尽量使文档读者确定或便于确定表示法的含义，除非双方默契。特别是文档编制者引用其他地方定义的语义源，即使这个语义源是标准的或广泛应用的语言，由于可能存在不同的版本，也应该使读者明确引用的具体版本。如果这样引用的一种表示法是用于内部开发的，就应该将其添加到内部技术文档编制所采用的符号体系中去。,第三节 合理文档的7条规则,2.3.4 避免歧义
22、,要点：标准结构有利于文档被更好的阅读和利用。,应该有计划的制定文档的标准结构方案，并确保文档的编制过程能够遵守，确保读者能够了解、理解。,标准结构文档至少具备以下优点：能够帮助读者在文档中导航和快速查询特定信息。能够帮助文档编写者计划和组织内容，并透露那些带有“待定”标签的节，还有什么工作等待完成。可以方便表达文档各节需要表达的重要特征集，这样可以体现信息完整性规则。,第三节 合理文档的7条规则,2.3.5 使用标准结构,要点：对基本原理进行记录可以节约大量的时间。,在编制决策结果的文档时，应该对被放弃的方案进行记录，并说明放弃的原因和理由。这样的记录，或者是将来接受详细检查或被迫更改的需要
23、，或者是为了以后可以重用设计。,通常在以下情况需要记录基本原理： 在做出决策前，设计团队必须花费大量时间评估各种候选方案； 决策对于某一需求或目标的实现很重要； 初看似乎决策意义不明，但细察其背景信息后，决策变得逐渐明朗； 在若干场合，有人向你提问：为什么这样做？ 为团队新成员解惑； 决策具有广泛影响，也难以消除这种影响； 你认为，现在捕捉基本原理，比以后捕捉更加经济划算。,第三节 合理文档的7条规则,2.3.6 记录基本原理,要点：人们总是乐意使用保持更新、内容精准的文档。,软件文档应该是该软件最终、最权威的信息源。通过引用合适的文档，我们能够最为容易、最为有效地回答关于该软件的问题。然而，
24、文档的更新却没有必要为那些无法持久的决策做出反映。这样做，其实是一种高成本和浪费资源的愚笨做法。事实上，应该在开发计划中指定文档更新的特定内容或过程，使文档服从版本控制，并制定一项文档发布策略，使得文档具有更好的服务特性。,第三节 合理文档的7条规则,2.3.7 使文档保持更新，但频度不要过高,要点：评审是文档保持有效的前提。,文档的预期用户是文档是否以正确的方式展示其正确内容的最好的评判者。应该寻求他们的帮助，在文档发布前，让文档所面向的预期用户(或代表)对文档进行评审。应该有有效的文档评审制度，以确保文档的质量和适用性。,第三节 合理文档的7条规则,2.3.8 针对目标的适宜性对文档进行评
25、审,03 文档编排管理,01 正确理解文档,02 文档编写的三个步骤,第一节 制定文档计划,3.1.1 步骤,附：,要点：,为制定文档计划或评估已有文档计划的完整性提供帮助。,第一节 制定文档计划,3.1.2 附：计划检查表,文档计划检查表： 文档计划编制好了吗？ 所需文档类型确定了吗？ 所需内容是否已列入提纲并描述？ 文档标准是否已确定？ 文档标准是否已经制定？ 有关编档、文档管理员、备用文档存储及文档评审职责分配了吗？ 质量准则建立了吗？ 有关提交草稿概要、初稿、修订稿、图示的计划表是否已经建立？ 评审日期是否确定？ 一个认可的周期是否确定？ 制作方法是否已选定并作出计划？,第一节 制定文
26、档计划,3.1.3 附：文档与项目过程对照表,某领域专家A先生就某企业的成本管理系统做用户需求报告的评审工作 在评审会开始时间不长，就被在场的某企业的一位副总B先生打断，认为A先生提出的方案不适合本企业，A先生提出的管理改进方案在企业中无法实施 该副总提完意见后，与会的用户方人员纷纷跟随B先生的提出了他们的反对意见，致使评审会无法再进行下去，最终该报告被用户否决。,例子,要点：,提高软件文档质量的一个有效方法就是在软件开发的各个阶段，对形成的文档进行严格评审。评审除了可以尽早发现问题，并及时采取措施予以解决，从而确保文档的正确性，同时，也为下一阶段的工作做好组织和技术上的准备。,1,案例,第二
27、节 做好文档评审,某软件公司为某公司A做业务流程管理系统的需求评审会 当项目组人员在会议上宣读多达上百页的需求报告时，用户明确提出听不懂，致使会议不得不改日进行。,例子,要点：,一次评审的内容太多，应分块进行评审，导致评审员的需求知识面覆盖不了。,2,第二节 做好文档评审,案例,某软件公司内部举行产品的需求评审会，主要是公司内部的相关领域的专家参加 在评审会开始后不久，某领域专家就对需求报告中的某个具体问题提出了自己的不同意见 与会人员纷纷就该问题发表自己的意见 大家争执不下，结果，致使会议出现了混乱状况，主持人无法控制局面，会议大大超出了计划评审时间。,例子,要点：,很多情况下，评审员是领域
28、专家而不是进行评审活动的专家，没有掌握进行评审的方法、技巧、过程等，需要培训 对于主持评审的管理者也需要进行培训，使参与评审的人员能够围绕评审的目标来进行，能控制评审节奏，提高评审效率,3,第二节 做好文档评审,案例,某软件公司在用户处开完物资管理系统的需求评审会后，与会人员在离开会议室时纷纷摇头，认为本次会议没有多少实际效果，完全是在走过场。 某软件公司在公司内部举行产品的需求评审会时，需求报告的执笔人与产品策划的主要策划人员的想法差别很大，致使需求评审会没有必要继续进行下去。,例子,要点：,找不到合格的评审员，与会的评审员无法提出深入的问题,4,第二节 做好文档评审,案例,1.分层次、分阶段评审,2.正式评审与非正式评审结合,3.充分准备评审,4.精心挑选评审员或培训,现有问题： 需求报告很长，短时间内评审者根本不能把需求报告读懂，想清楚 没有作好前期准备工作，需求评审的效率很低 需求评审的节奏无法控制 找不到合格的评审员，与会的评审员无法提出深入的问题,5.充分利用需求评审检查单,6.做好评审后的跟踪工作,3.2.1 文档评审的7大建议,第二节 做好文档评审,3.2.2 附：软件开发过程各评审点文档评审内容要点,第二节 做好文档评审,
