搜索
第1页XX公司项目经理内训如何写好文档xxx2016-04LOGO第2页01正确理解文档02文档编写的三个步骤03文档编排管理ContentsPage目录页第2页第3页TransitionPage过渡页第3页01正确理解文档02文档编写的三个步骤03文档编排管理第4页第一章正确理解文档软件（英文：Software）是一系列按照特定顺序组织的计算机数据和指令的集合。一般来讲软件被划分为系统软件、应用软件和介于这两者之间的中间件。软件并不只是包括可以在计算机（这里的计算机是指广义的计算机）上运行的电脑程序，与这些电脑程序相关的文档一般也被认为是软件的一部分。简单的说软件就是程序加文档的集合体。另也泛指社会结构中的管理系统、思想意识形态、思想政治觉悟、法律法规等等。。1.1.1什么是软件？第一节软件文档概念软件=程序+文档第5页第一章正确理解文档1.1.2为什么需要软件文档？第一节软件文档概念告诉用户如何操作和维护系统提供关于未来改进和重新实施所需的信息在开发人员、维护人员、管理人员、用户与计算机之间起着重要的桥梁作用维护人员管理人员计算机软件用户桥梁作用开发人员第6页第一章正确理解文档项目管理的依据：文档将通常“不可见的”软件开发进程转换成“可见的”文字资料，有利于项目的管理。。技术交流的语言：项目小组内部、项目平行开发的各小组之间进行的交流和联系，通常都是通过文档来实现的。项目质量保证：文档是进行项目质量审查和评价的重要依据，有效文档的提供，可以满足项目质量保证人员和审查人员的工作需要。支持培训与维护：合格的软件文档通常都提供有关软件运行、维护和培训的必要信息，支持软件产品的应用。支持软件维护：软件文档提供系统开发的全部必要技术资料，有利于维护人员熟悉系统，开展维护工作；软件维护文档记载了软件维护过程中软件及其环境变化的全部信息。记载软件历史：软件文档作为“记载软件历史的语言”，可用作未来项目的一种资源，向潜在用户报道软件的各种有利信息，便于他们判断自己是否需要该软件提供的服务。第一节软件文档概念1.1.3文档的作用第7页第一章正确理解文档第二节软件文档分类1.2.1根据产生和使用范围分软件文档开发文档用户文档管理文档￭可行性研究报告￭项目开发计划￭软件需求说明书￭数据库设计说明书￭概要设计说明书￭详细设计说明书￭用户手册￭操作手册￭软件需求说明书￭数据要求说明书￭项目开发计划￭开发进度月报￭测试计划￭测试分析报告￭项目开发总结报告第8页第一章正确理解文档1.2.2开发文档开发文档主要可以发挥以下几个方面的作用：•作为软件生存期整个阶段之间的通信工具，记录生成软件需求、设计、编码、测试等的详细规定和说明；•描述开发小组的工作职责。通过规定软件规划设计、主题事项、文档编制、质量保证等人员的角色，来定义“如何做”和“何时做”；•用作检验点，而允许管理者评估开发进度。如果开发文档缺失或过时，管理者将失去跟踪和控制软件项目的重要工具；•形成系统维护人员所要求的基本的软件支持文档，并构成产品文档的一部分；•记录软件开发的历史。开发文档主要负责对软件开发过程进行描述和规范。开发文档除了前面列表的内容，还包括软件的详细技术描述，如程序逻辑、程序间相互关系、数据格式、存储等。第二节软件文档分类第9页第一章正确理解文档1.2.3用户文档用户文档主要发挥以下作用：•为使用和运行软件产品的用户提供培训和运行参考信息；•为产品维护工程师提供必要的信息；•促进和方便软件产品的市场推广。用户文档主要负责对软件产品的安装、配置、使用、维护等信息进行描述。包括系统安装配置手册、用户操作手册、软件需求说明书、数据要求说明书等。第二节软件文档分类第10页第一章正确理解文档1.2.4管理文档管理文档主要有以下作用：•软件初期定义、规划、商务等与客户互动结果的记录；•开发过程每个阶段的进度和进度变更的记录；•软件开发人员的组织、管理和变更的记录；•软件需求、规划、设计等的变更控制的记录；•开发过程发生的各种审查、审核、评估等情况的记录；•验收、培训、移交、安装等相关工作的实施记录；•维护需求的提出、认定、计划、实施等工作的记录。管理文档主要是对软件开发过程的管理信息进行描述。管理文档除了前面列表内容，还应该包括被管理者的反馈信息，如各色表格、工作总结、开发体会、产品建议等。第二节软件文档分类第11页第二章文档编写的三个步骤软件文档最终需要回答读者关心的下列问题：二、What工作目标要满足哪些需求？三、How需求应如何实现？四、Who开发、维护或修改的工作应由谁来完成？五、When开发工作的时间如何安排？六、Where开发工作在什么环境中实现，所需信息从何而来？一、Why为什么要开发、维护或修改这个软件？第三节软件文档最终需要回答的问题第12页TransitionPage过渡页第12页01正确理解文档02文档编写的三个步骤03文档编排管理第13页第二章文档编写的三个步骤诗歌是思想的疑聚，廖廖几行诗歌能表现极为复杂的思想。那么，软件文档如何表达？。第一节引言2.1.1诗歌与编码第14页第二章文档编写的三个步骤第一节引言2.1.2知其然通常版本的故事是这样的……仅听命令上司：领导要来，今天给我去做个项目汇报PPT你：明天？！熬夜苦战老婆：有没有搞错？！你又加班？！你：唉~~没办法啦！你先睡吧……彻底崩溃领导：你的报告我看过了，思路不对，重做！你：完了，今晚又要通宵了……第15页第二章文档编写的三个步骤第一节引言2.1.3知其所以然高手的故事是这样的……问清缘由上司：领导要来，今天给我去做个项目汇报PPT高手：主要是讲给谁听的？听众是什么级别？这个汇报希望着重阐述哪几个观点？构思脉络高手(构思)：这个议题应该可以分这样三个小议题，每个小议题之间的逻辑是“问题-思路-举措“，咦，采购是Mary管的，必须打电话给她，问她要材料……轻松应对领导：你的报告我看过了，思路正确，有几页建议你做一下微调！高手(心里想)：今天晚上可以陪老婆看电影去咯……第16页第二章文档编写的三个步骤步骤分解说明文档编制者在编写文档时，通常会采用两种形式：意识流或执行流。意识流：按思维在编写者头脑中出现的顺序捕捉思维，并加以记录。通常缺乏可读的组织结构。执行流：按软件执行时的思维顺序捕捉思维，并加以记录。缺乏重点内容的突出展现。01情景分析写给谁看？写什么？需要达到什么效果？…用什么顺序？是否需要拆分文档？能否说明问题？…是否抓住重点？是否有重复？是否有歧义？…第二节文档编写的三个步骤2.2.1步骤分解结构设计02提炼美化03第17页第二章文档编写的三个步骤2.2.2文档涉众对像对照第二节文档编写的三个步骤开发人员维护人员管理人员营销人员用户可行性研究报告√√√项目开发计划√√√软件需求说明书√√数据要求说明书√测试计划√√概要设计说明书√√详细设计说明书√√数据库设计说明书√√用户手册√√操作手册√√测试分析报告√√开发进度月报√项目总结报告√维护和修改建议√产品市场宣传资料√√√第18页第二章文档编写的三个步骤2.2.3文档内容编写对照第二节文档编写的三个步骤为什么(Why)做什么(What)怎么做(How)谁来做(Who)何时做(When)何处做(Where)可行性研究报告√√项目开发计划√√√软件需求说明书√√数据要求说明书√√测试计划√√√概要设计说明书√详细设计说明书√数据库设计说明书√用户手册√操作手册√测试分析报告√开发进度月报√√项目总结报告√维护和修改建议√√√√√第19页第二章文档编写的三个步骤在开始软件文档编写前，首先要考虑的是:如何对文档内容进行组织?由于软件系统的特殊性,其内容表达的组织方式也有自己独特的如下几种可选择的方式：就是文档的编制大纲。反映文档组织构架的“初步设计内容表”把收集的材料归类。介绍文档的核心内容和主题思想及文档的组织结构等，一般300—500字为宜。②建立初步的文档组织内容表③摘要①确定组织类型按重要性的顺序。如培训资料等的绪论按由简及繁的顺序。如用户手册文档按时间/软件的运行顺序。一般的步骤说明要用此方式分析法。把复杂问题分解为若干个主要问题进行说明，如文档的绪论部分专题法。如按功能分类组织内容2.2.4软件文档的内容组织第二节文档编写的三个步骤第20页第二章文档编写的三个步骤01直叙式02编号指教式03剧本式04四步法2.2.5选择文档写作表达方式第二节文档编写的三个步骤编制软件文档时，应该根据不同文档的性质、类型以及涉众的类型、专业能力等，在确定文档编制计划、内容和步骤后，还要确定文档编制的表达方法。需要编入文档的资料以怎样的方式表达，对该文档涉众以及软件产品、文档等的传播有很大的影响。第21页第二章文档编写的三个步骤点击“取消确认”按钮取消确认账单，账单状态由已确认改为未确认。需校验当前用户角色所属组织的结算公司是否与账单的结算公司一致，若不一致，不允许取消确认。提示用户：当前用户角色所属组织的结算公司是否与账单的结算公司不一致，不允许取消确认。还需校验账单是否已被合并，若已合并，提示用户：账单已合并，不允许取消确认。若当前用户角色所属结算公司的办事处配置要求必须做账单，则还需校验账单是否含有已开票或部分开票、已请款或部分请款、已核销或部分核销的费用。若含有已开票或部分开票的费用，提示用户：账单含有已开票或部分开票的费用，不允许取消确认。若含有已请款或部分请款的费用，提示用户：账单含有已请款或部分请款的费用，不允许取消确认。若含有已核销或部分核销的费用，提示用户：账单含有已核销或部分核销的费用，不允许取消确认。要点：注意这种方式会使某些信息在段落中丢失。第二节文档编写的三个步骤2.2.6直叙式按照文档中上下文关系，平铺直叙需要编入文档的内容。这是多数文档常用的表达形式。下图是一个直叙式编档的例：第22页第二章文档编写的三个步骤2.取消确认账单2.1用户点击“取消确认”按钮2.2系统校验当前用户角色所属组织的结算公司是否与账单的结算公司一致，若不一致，不允许取消确认并提示用户：当前用户角色所属组织的结算公司是否与账单的结算公司不一致，不允许取消确认。2.3系统校验账单是否已合并，若已合并，提示用户：账单已合并，不允许取消确认。2.4系统校验账单是否含有“已开票”或“部分开票”的费用，如果有则提示用户：账单含有已开票或部分开票的费用，不允许取消确认。2.5系统校验账单是否含有“已请款”或“部分请款”的费用，如果有则提示用户：账单含有已请款或部分请款的费用，不允许取消确认。2.6系统校验账单是否含有“已核销”或“部分核销”的费用，如果有则提示用户：账单含有已核销或部分核销的费用，不允许取消确认。2.7如果校验通过，系统更改账单状态由“已确认”改为“未确认”。要点：这种表达方式使需要完成的工作十分明确，且数据的长度、格式也有规定，尽管占用的空间稍大，但阅读方便，能使读者快速找到需要的内容。第二节文档编写的三个步骤2.2.7编号指教式以菜谱式为基础，将文档中描述的软件工作步骤或处理过程加以编号，其表达结果会比直叙式更适合阅读理解。第23页第二章文档编写的三个步骤订购员：1.完成订购输入单(P0123)a.订购号：预先印在单据上的顺序号b.日期：输入当前日期。采用yyyymmdd的8位表达，如将2005年12月1日表示为20051201c.供货企业：输入接受订货的企业名。最多25个汉字d.货号：输入要订购的货号。在库存清单中找货号。若为新增，则见新增货物部分……操作员：2.将订购单输入计算机系统员：3.数据录入计算机，并更新订购文件要点：剧本式会比编号指教式占用更多的篇幅，直叙法使文档内容泛而无重点，编号指教法则突出执行者即角色的作用欠缺。而剧本法者使角色的任务十分鲜明，不同用户只需阅读相关部分即可。第二节文档编写的三个步骤2.2.8剧本式将文档以剧本方式表达。也有“演员”，以及动作。下图是这种方法的例：第24页第二章文档编写的三个步骤提单打印命令利用打印命令，可得到提单的纸质拷贝。在一页纸上的打印宽度和纸的宽度有关。通过指定上、下边缘及