浅谈软件文档管理

【摘要】 软件文档是指某种媒体和其中所记录的数据，具有永久性，并可由人或机器阅读，仅用于人工可读的内容。在软件工程中，文档常用来表示对活动、需求、过程或结果进行描述、定义、规定、报告、认证的任何书面或图示的信息。软件文档是软件产品必不可少的组成部分，高质量、高效率地管理和维护软件文档，对于转让、变更、修正、扩充和使用软件及充分发挥软件产品的效益有着重要的意义。

【关键词】 软件文档；软件工程；设计和实现；管理和维护

一、软件文档的作用

（1）管理依据。在软件开发过程中，管理者必须了解开发进度、存在的问题和预期目标。每一阶段计划安排的定期报告提供了项目的可见性，定期报告还提醒各级管理者注意该部门对项目承担的责任及该部门效率的重要性。开发文档规定若干个检查点和进度表，使管理者可评定项目的进度。如果开发文档有遗漏、不完善或内容陈旧，管理者将失去跟踪和控制项目的重要依据。（2）任务之间联系的凭证。大多数软件开发项目通常被划分成若干任务，由不同的小组去完成，学科方面的专家建立项目，分析员阐述系统需求，设计员为程序员制定总体设计，程序员编制详细的程序代码，质量保证专家和审查员评价整个系统性能和功能的完整性，负责维护的程序员改进各种操作或增强某些功能。这些人员需要的互相联系是通过文档资料的复制、分发和引用而实现的，因而任务之间的联系是文档的一个重要功能。大多数系统开发方法为任务的联系规定了一些正式文档。分析员向设计员提供正式需求规格说明，设计员向程序员提供正式设计规格说明等等。（3）质量保证。对于负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用的各种质量标准以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明；必须制订测试计划和测试规程，并报告测试结果；还必须说明和评估完全、控制、计算、检验例行程序及其他控制技术。这些文档的提供可满足质量保证人员和审查人员上述工作的需要。（4）培训与参考。软件文档的另一个功能是使系统管理员、操作员、用户、管理者和其他有关人员了解系统如何工作，以及为了达到各自的目的，如何使用系统。（5）维护支持。维护人员需要软件系统的详细说明书以帮助熟悉系统，尽可能找出并修正错误、改进系统，以适应用户需求的变化或适应系统环境的变化。(6)历史档案。软件文档可用作未来项目的一种资源。通常文档记载系统的开发历史，可使有关系统结构的基本思想为以后的项目所利用。系统开发人员通过审阅以前的系统以查明什么部分已试验过，什么部分运行的很好，什么部分因某种原因难以运行而被排除。良好的系统文档有助于把程序移植到新的系统环境中。

二、软件文档管理在项目进程中的重要作用

软件文档管理，是指在一个系统(软件)项目开发进程中将提交的文档进行收集管理的过程。文档管理在项目开发中不是很受重视，当发现其重要性时，已经为时已晚。整个项目可能因此变得管理混乱，问题无据可查。作为管理完善的项目文档，管理者完全可依顺它的轨迹看清整个项目进展的脉络，通过对阶段性文档的把握使整个项目质量得到很好的掌控。制定一套完整有序的项目文档管理规定十分必要，其作用有以下6个方面。（1）它是项目管理者了解开发进度、存在的问题和预期目标的管理依据。（2）大多数软件开发项目会被划分成若干个任务，并由不同的组去完成。文档管理则是不同小组任务之间联系的重要凭证。（3）可提供完整的文档，保证项目开发的质量。（4）项目文档是系统管理员、操作员、用户、管理者和其他相关人员了解系统如何工作的培训与参考资料。（5）项目文档将为系统维护人员提供维护支持。（6）项目文档作为重要的历史档案将成为新项目的开发资源。

现在大多数金融、通信企业为了更好的服务客户、准确掌握自身数据，都在不遗余力地建立数据仓库系统。企业数据仓库(EDW)从筹建项目组到软件开发建设再到系统上线维护，基本涉及了软件项目建设的所有环节，对文档管理提出了较全面的要求。以下就EDW建设为例作了探讨，首先，借助VSS软件建立项目文档管理服务器以保存所有的项目文档。其次，项目保存的文档要涵盖项目管理、项目调研、项目开发、项目应用、系统管理、系统测试验收、项目培训、版本控制、数据质量管理、用户手册、系统上线等整个项目周期。从项目管理者的亲身体会来讲，这些文档的保存往往是混乱无序、无法快捷地获得所需信息。究其原因，项目组在系统开发过程中虽然很重视文档的保存，但是忽视了文档的管理。文档归档没有正式的管理要求，缺少文档提交的依据和规则。最后，建立文档管理规定。由于项目文档管理员按照规定对文档进行管理，因此项目经理及小组成员都能快速得到自己所需的各类文档。项目经理还可很清晰地透过项目文档把握项目进展情况。

三、如何建立软件文档管理规定

从不同的行业和项目的个性出发，需要管理者结合实际情况制订出适合自身文档管理的规定。《软件文档管理指南》和《计算机软件产品开发文件编制指南》(以下统称《指南》)给提供了相关的指导。首先要明确关于软件项目文档的具体分类。《指南》中提出文档从重要性和质量要求方面可分为非正式文档、正式文档；从项目周期角度可分为开发文档、产品文档、管理文档；更细致还可分为l4类文档文件，具体有：可行性研究报告、项目开发计划、软件需求说明书、数据要求说明书、概要设计说明书、详细设计说明书、数据库设计说明书、用户手册、操作手册、模块开发卷宗、测试计划、测试分析报告、开发进度月报、项目开发总结报告。这样的分类细化了项目进度中各个阶段所需管理的文档。其次需要将项目文档进行归类整理。对EDW项目组文档情况与软件文档管理指南进行对比分析，可以看出，没有规范管理的EDW项目组文档存在以下4方面问题。（1）项目组在开发初期针对业务部门和科技部门进行了需求及信息调研，可覆盖部分软件需求和数据需求说明书的内容，但缺少业务部门对项目需求描述和变更的文档记录。这部分文档需建立相应目录予以保存。（2）对于设计说明，在系统较复杂的情况下，设计阶段应分解成概要设计和详细设计两个步骤。目前EDW项目组只对ETL模块提供了概要设计说明书，并没有单独的存放目录，而是同其他设计文档混乱地放在一起。对于比较复杂的应用开发项目，应将这两种设计说明文档分目录管理。（3）在项目测试验收中，项目组没有要求将测试计划文档和测试结果报告进行规档，只重视了测试过程中的问题文档，因此无法掌控测试进度与质量。（4）EDW项目组的工作分为模型设计、ETL、集市应用3个工作小组，对应的文档管理需要围绕这3个主题进行。其中模型设计和ETL都是数据仓库项目实施的模块，集市应用则包括建立在数据仓库基础上的小项目开发。因此，文档管理也应该针对这3个部分不同的性质制定管理规则。

针对EDW文档管理存在的问题，EDW项目组最终依据通用规则建立了正式的项目文档管理规定。具体规定有以下5点。（1）将文档分为两大部分提交管理。项目常规文档和项目归档文档。常规文档的提交和使用根据项目组内部小组成员任务的不同进行权限划分；项目归档文档由项目管理主管(或项目文档管理员)将项目中的重要文档从常规文档中进行分类归档。（2）常规文档管理目录分为项目日常管理文档和项目流程管理文档。（3）日常管理文档包括项目报告、会议纪要、项目管理模板、重大问题跟踪、数据质量管理。项目报告可分为个人周报、小组周报、项目周报、项目简报，项目简报。并都按照不同目录进行分类管理。（4）提交完整的项目开发、应用开发流程文档。一般包括项目计划、业务需求说明书、数据需求说明书、模块、应用开发文档、系统测试文档、详细设计文档、系统测试文档、用户手册、上线文档、培训资料、系统运行维护等。（5）所有项目组成员均建立VSS软件环境下的对应用户，各自拥有对以上各类文档的读、写、增加、删除权限。由各项目小组长保证提交已保存文档的质量；由文档管理员或项目经理整体把握项目文档在各阶段的提交情况。

参考文献

[1]李成大.软件工程基础[M].北京:电子工业出版社，2003

[2]金光伟，林朔.电子档案浅析[J].洛阳大学学报，2000：15(4)

[3]王春森.程序设计（高级程序员级）[M].北京:清华大学出版社，1999