软件开发文档管理规范

1、编辑课件软件项目管理培训讲座软件项目管理培训讲座系列之三系列之三文档管理规范文档管理规范3/11/2022编辑课件2内容提要内容提要文档的分类和等级文档的分类和等级文档管理的原则和方法文档管理的原则和方法文档示例与讨论文档示例与讨论3/11/2022编辑课件3为什么需要文档管理？为什么需要文档管理？项目管理的依据项目管理的依据了解进度、分析问题，提供项目可预见性了解进度、分析问题，提供项目可预见性工作交流的凭证工作交流的凭证口说无凭，立字为据口说无凭，立字为据软件测试的基础软件测试的基础没有文档，测试人员无法展开工作没有文档，测试人员无法展开工作培训用户的参考培训用户的参考帮助外界人员了解项目

2、内幕帮助外界人员了解项目内幕技术支持的帮手技术支持的帮手帮助技术支持人员熟悉系统、分析错误、解决问题帮助技术支持人员熟悉系统、分析错误、解决问题记录历史的必须记录历史的必须软件最大的价值在于可复用性软件最大的价值在于可复用性3/11/2022编辑课件4为什么需要文档管理？为什么需要文档管理？3/11/2022编辑课件5编写文档的基本思路编写文档的基本思路明确文档范围，避免空泛浮躁明确文档范围，避免空泛浮躁大而全的文档是没有用的大而全的文档是没有用的定位读者角度，防止对牛弹琴定位读者角度，防止对牛弹琴以读者能够理解作为编写文档的标准以读者能够理解作为编写文档的标准规范名词称谓，保持前后一致规范名

3、词称谓，保持前后一致统一的名词和称谓，会降低文档的歧义性统一的名词和称谓，会降低文档的歧义性注重版本控制，切忌顾此失彼注重版本控制，切忌顾此失彼不同阶段的文档记录了项目开发的完整过程不同阶段的文档记录了项目开发的完整过程应用图文表格，保证内容清晰应用图文表格，保证内容清晰简洁的图形和表格胜过前言万语简洁的图形和表格胜过前言万语3/11/2022编辑课件6文档的分类（文档的分类（1 1）类型类型读者读者时间时间可行性研究报告可行性研究报告管理管理/ /研发人员研发人员可行性研究与计划阶段可行性研究与计划阶段项目开发计划项目开发计划管理管理/ /研发人员研发人员可行性研究、需求分析阶段可行性研究、

4、需求分析阶段设设需求规格说明书需求规格说明书研发人员研发人员需求分析阶段需求分析阶段计计功能规格说明书功能规格说明书研发人员研发人员需求分析阶段需求分析阶段开开概要设计说明书概要设计说明书研发研发/ /维护人员维护人员设计阶段设计阶段发发详细设计说明书详细设计说明书研发研发/ /维护人员维护人员设计阶段设计阶段类类数据库设计说明书数据库设计说明书研发研发/ /维护人员维护人员设计阶段设计阶段模块开发卷宗模块开发卷宗管理管理/ /研发研发/ /维护人员维护人员实现、测试阶段实现、测试阶段测试计划测试计划研发人员研发人员需求分析、设计阶段需求分析、设计阶段测试分析报告测试分析报告研发研发/ /维护

5、人员维护人员测试阶段测试阶段管管开发进度月报开发进度月报管理人员管理人员贯穿整个开发过程贯穿整个开发过程理理项目开发总结项目开发总结管理人员管理人员测试阶段测试阶段类类职责定义职责定义管理人员管理人员可行性研究与计划阶段可行性研究与计划阶段进度变更记录进度变更记录管理人员管理人员随时随时产产用户指南用户指南用户用户需求分析、设计、实现阶段需求分析、设计、实现阶段品品操作手册操作手册用户用户设计、实现阶段设计、实现阶段类类信息广告信息广告用户用户测试阶段测试阶段3/11/2022编辑课件7文档的分类（文档的分类（2 2）文件文件 阶段阶段可行性研究可行性研究与计划阶段与计划阶段需求分需求分析阶段

6、析阶段设计设计阶段阶段实现实现阶段阶段测试测试阶段阶段运行与运行与维护阶段维护阶段数据需求说明书数据需求说明书项目开发计划项目开发计划软件需求说明书软件需求说明书数据需求说明书数据需求说明书测试计划测试计划概要设计说明书概要设计说明书详细设计说明书详细设计说明书数据库设计说明书数据库设计说明书模块开发卷宗模块开发卷宗用户手册用户手册操作手册操作手册测试分析报告测试分析报告开发进度月报开发进度月报项目开发总结项目开发总结3/11/2022编辑课件8文档的分类（文档的分类（3 3）开发文档开发文档可行性研究报告可行性研究报告项目开发计划项目开发计划模块开发卷宗模块开发卷宗测试分析报告测试分析报告需

7、求规格说明书需求规格说明书功能规格说明书功能规格说明书概要设计说明书概要设计说明书详细设计说明书详细设计说明书数据库设计说明书数据库设计说明书测试计划测试计划3/11/2022编辑课件9文档的分类（文档的分类（4 4）产品文档产品文档用户指南用户指南操作手册操作手册用户指南用户指南产品手册产品手册3/11/2022编辑课件10文档的分类（文档的分类（5 5）管理文档管理文档开发进度月报开发进度月报项目开发总结项目开发总结职责定义职责定义进度变更记录进度变更记录3/11/2022编辑课件11文档的等级（文档的等级（1 1）确定文档质量等级确定文档质量等级根据项目资源、项目大小和风险确定每个文档根

8、据项目资源、项目大小和风险确定每个文档的格式及详细程度的格式及详细程度文档格式和文档内容同样重要文档格式和文档内容同样重要必须保证文档的质量，文档管理才有意义必须保证文档的质量，文档管理才有意义 3/11/2022编辑课件12文档的等级（文档的等级（2 2）文档按照质量可划分为四个等级：文档按照质量可划分为四个等级：最低限度文档（最低限度文档（1 1级文档）级文档）适合开发工作量低于一个人月的开发者自用程序适合开发工作量低于一个人月的开发者自用程序包含程序清单、开发记录、测试数据和程序简介包含程序清单、开发记录、测试数据和程序简介内部文档（内部文档（2 2级文档）级文档）适合于没有与其他用户共

9、享资源的专用程序适合于没有与其他用户共享资源的专用程序1 1级文档内容，加上足够的注释和说明级文档内容，加上足够的注释和说明3/11/2022编辑课件13文档的等级（文档的等级（3 3）文档按照质量可划分为四个等级：文档按照质量可划分为四个等级：工作文档（工作文档（3 3级文档）级文档）适合于由同一单位内若干人联合开发的程序，或适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序可被其他单位使用的程序正式文档（正式文档（4 4级文档）级文档）适合那些要正式发行供普遍使用的软件产品适合那些要正式发行供普遍使用的软件产品关键性程序或具有重复管理应用性质（如工资计关键性程序或具有重复管理

10、应用性质（如工资计算）的程序需要算）的程序需要4 4级文档级文档3/11/2022编辑课件14内容提要内容提要文档的分类和等级文档的分类和等级文档管理的原则和方法文档管理的原则和方法文档示例与讨论文档示例与讨论3/11/2022编辑课件15文档管理的基本原则文档管理的基本原则完整性原则完整性原则项目文档集应覆盖软件开发的完整流程项目文档集应覆盖软件开发的完整流程简洁性原则简洁性原则编写文档不应浪费过多的时间和经历编写文档不应浪费过多的时间和经历有效性原则有效性原则文档必须能够起到辅助决策、指导参考的作用文档必须能够起到辅助决策、指导参考的作用延续性原则延续性原则文档的变化必须有合理依据，保持连

11、续发展文档的变化必须有合理依据，保持连续发展3/11/2022编辑课件16文档管理的内容文档管理的内容建立文档规范，培养良好习惯建立文档规范，培养良好习惯制定编写计划，明确编写责任制定编写计划，明确编写责任检查文档质量，提高利用效率检查文档质量，提高利用效率控制文档范围，保护知识产权控制文档范围，保护知识产权实施版本控制，有效记录历史实施版本控制，有效记录历史3/11/2022编辑课件17文档管理方法：如何命名？文档管理方法：如何命名？命名规范的重要性命名规范的重要性统一的对外形象（举例）统一的对外形象（举例）有效的文档分类（举例）有效的文档分类（举例）快速的文档查找（举例）快速的文档查找（举

12、例）命名规则的制定命名规则的制定并无统一规则，依据项目环境自定义并无统一规则，依据项目环境自定义技巧技巧1 1：确定统一的空白封面和项目名称：确定统一的空白封面和项目名称技巧技巧2 2：同类型多个文档的命名方法：同类型多个文档的命名方法技巧技巧3 3：文档存储和管理的方法：文档存储和管理的方法3/11/2022编辑课件18文档管理方法：如何保证内容完整？文档管理方法：如何保证内容完整？内容残缺的体现内容残缺的体现缺少项目背景和内容目录（举例）缺少项目背景和内容目录（举例）缺少表格和示意图（举例）缺少表格和示意图（举例）缺少对思想的阐述和问题的分析（举例）缺少对思想的阐述和问题的分析（举例）保证

13、内容完整的方法保证内容完整的方法技巧技巧1 1：提供统一的项目背景资料：提供统一的项目背景资料技巧技巧2 2：培养一致的文档编写习惯：培养一致的文档编写习惯技巧技巧3 3：明确要求表格和图形的使用方式：明确要求表格和图形的使用方式3/11/2022编辑课件19文档管理方法：如何写好需求分析文档管理方法：如何写好需求分析做好需求分析的前提条件做好需求分析的前提条件客户应用环境的了解客户应用环境的了解市场主流与技术主流的了解市场主流与技术主流的了解客户现有需求的总结和潜在需求的挖掘客户现有需求的总结和潜在需求的挖掘完成需求分析的过程完成需求分析的过程第一步：项目建议书（第一步：项目建议书（Prop

14、osalProposal） 第二步：市场与技术调研报告（第二步：市场与技术调研报告（M&T Report)M&T Report)第三步：需求变更风险分析第三步：需求变更风险分析第四步：需求分析初稿第四步：需求分析初稿3/11/2022编辑课件20文档管理方法：如何写好概要设计文档管理方法：如何写好概要设计做好概要设计的前提条件做好概要设计的前提条件客户需求细节的了解客户需求细节的了解技术重点和难点的分析技术重点和难点的分析系统结构的设计与划分系统结构的设计与划分完成概要设计的过程完成概要设计的过程第一步：功能描述（第一步：功能描述（Function DescriptionFun

15、ction Description）第二步：功能定义（第二步：功能定义（Function SpecificationFunction Specification）第三步：重点难点问题解决思路第三步：重点难点问题解决思路第四步：概要设计草案第四步：概要设计草案3/11/2022编辑课件21文档管理方法：如何写好详细设计文档管理方法：如何写好详细设计详细设计的底线是什么？详细设计的底线是什么？主要处理流程的详细说明主要处理流程的详细说明对外接口的详细说明对外接口的详细说明主要逻辑结构和数据结构的详细说明主要逻辑结构和数据结构的详细说明完成详细设计的过程完成详细设计的过程第一步：流程定义（第一步：流

16、程定义（Control FlowControl Flow）第二步：数据结构定义（第二步：数据结构定义（Data Flow)Data Flow)第三步：接口定义（第三步：接口定义（API SpecificationAPI Specification）第四步：详细设计草案第四步：详细设计草案3/11/2022编辑课件22文档管理方法：如何写好里程碑报告文档管理方法：如何写好里程碑报告里程碑报告的内容里程碑报告的内容预期目标的解释和说明预期目标的解释和说明已完成工作的说明已完成工作的说明进度情况、测试结果的分析和说明进度情况、测试结果的分析和说明下一步工作的重点和难点下一步工作的重点和难点完成里程碑

17、报告的过程完成里程碑报告的过程第一步：分析前一个里程碑报告的内容第一步：分析前一个里程碑报告的内容第二步：说明当前里程碑的主要进展第二步：说明当前里程碑的主要进展第三步：总结存在的问题、困难和障碍第三步：总结存在的问题、困难和障碍第四步：列出下一个里程碑的主要工作计划第四步：列出下一个里程碑的主要工作计划3/11/2022编辑课件23文档管理方法：确定最小文档集文档管理方法：确定最小文档集如何确定最小文档集如何确定最小文档集重要认识：最小文档集不是指最简单文档集重要认识：最小文档集不是指最简单文档集最重要、最必须的文档组成最小文档集最重要、最必须的文档组成最小文档集如何实现最小文档集如何实现最

18、小文档集人员分工：多人协作完成一份文档人员分工：多人协作完成一份文档文档格式：提供统一易用的模板文档格式：提供统一易用的模板内容组织：合并细节结构，保持总体完整内容组织：合并细节结构，保持总体完整3/11/2022编辑课件24反思：为什么中国人不善于写文档？反思：为什么中国人不善于写文档？文化背景的原因文化背景的原因官修史与私修史：从孔子谈起官修史与私修史：从孔子谈起封建专制与思想禁锢：焚书坑儒和文字狱封建专制与思想禁锢：焚书坑儒和文字狱现代教育的原因现代教育的原因缺乏方法教育和人格教育缺乏方法教育和人格教育缺乏法律意识和严谨态度缺乏法律意识和严谨态度官本位、钱本位的价值观官本位、钱本位的价值观3/11/2022编辑课件25内容提要内容提要文档的分类和等级文档的分类和等级文档管理的原则和方法文档管理的原则和方法文档示