软件项目文档管理中折射出的管理理念

软件项目文档管理中折射出的管理理念

在软件开发项目当中，文档管理是必不可少的内容，其必要性无人可以否认，但是，一套“规范”的文档，也经常会让人抓狂，“浪费”很多时间在文档上面。在经历过许多实际的软件研发项目，和多次的制定组织级软件研发项目规范工作，对于软件研发项目中的文档管理有不少的体会，在软件项目的文档管理中，如何使文档管理更加有效，实际能够折射出许多的管理理念。保证有效沟通文档的主要作用是用于沟通，在所有的软件规划、设计、实现、运行、使用、服务等相关人员之间的信息交换。在文档编写过程中，要求所传递信息做到完整、准确、简洁，特别是要能够适合读者理解。紧紧抓住信息沟通这一核心目的，对于无论是制作文档模板还是编制具体文档，都是很重要的指导思想。记得早年学习过国标的软件工程文档规范，不仅文档很多，而且很多的文档的第一章都是背景介绍，曾经试图按照这种规范来编写文档，第一章写了几行就实在是写不下去了，这确实会令许多的软件开发人员感到抓狂，在今天更加强调响应速度的开发过程要求来说，几乎是无法执行的。因此，在编写文档时，关键就抓住两点：一时明确文档的读者对象，二是站在读者角度把读者希望了解的信息完整、准确、简洁的描述清楚。写文档和读文档，就如同是作者与读者之间在对话，把要传递的内容描述清楚，文档的目的就达到了。啰里啰嗦的无关内容，不仅浪费作者和读者的时间，也会影响对文档重要信息的突出。与所采用的工程方法相匹配在软件研发方面有许多不同的工程方法，瀑布式、原型法、敏捷开发等等，不同的开发过程实际意味着不同的生产工艺，那么在不同的工艺方法中各道工序的工作内容和要求不同、工序之间的衔接要求不同，必然也会对文档的要求产生不同。因此，在编写文档时，也需要考虑开发项目中所采用的工程方法的因素，在单位制定软件开发文档模板时，也需要考虑不同的文档体系，以支持不同的开发过程方法。经得住事后审计作为交付物的文档，必须要能够清晰记载各种事项的来龙去脉和因果关系，对于一些重要的决策要记录其关键过程，也就是说，无论是从专业角度还是从管理角度，对于形成逻辑关系的关键内容都要形成文档记录，不仅便于后续环节的理解，更要能够经得起事后的审计。所以，对于一些比较重要的技术类和管理类文档，从事后审计的角度来审视文档内容，确实也是一个很好的视角。在很多单位当中，一份逻辑严谨、经得起审计的文档，越来越重要。区分文档的记录与整理很多很多的人对于文档都很头疼，需要花费很多“额外”的时间来编写，但实际上我们看到，许多需要在文档记载的实质内容其实并不缺少，在软件研发的项目过程中，该讨论、该沟通的内容实质并不少。对此稍作区分可以看出，问题出在“整理”文档上。所以在实践中，可以将文档的形成分成两个阶段，一是在过程中形成的记录，这些记录可以是手画的草图拍成照片，可以是简单的会议记录，也可以是工具软件本身生成的特殊格式的输出文件，比如数据库设计文档、项目计划文档，这些专业工具形成的特殊格式的文件，其实比转换成EXCEL或PDF文档要好用，而且能够真正在后续的执行中继续发挥作用。能反映实质内容的这些记录形式，其实也是文档!在项目进程告一段落后，再对这些原始的记录进行整理，去除冗余信息，形成更为规范、易读的制式文档。在信息管理当中有一个基本原则，就是要在产生信息的地方收集信息才是最有效的。将文档的形成过程分成记录和整理两个阶段，用各种最方便的形式首先进行记录，这样也是可以作为文档满足实际需要和各种质量体系的要求，以后再经过整理形成可供后人查阅的文档，不必非要在紧张的开发项目过程中进行文档整理工作。区分项目文档与产品文档在文档管理中，还经常遇到项目文档和产品文档的问题。在软件研发项目中，一个项目任务的完成，经常需要多个软件系统(产品)的共同配合，从而会形成项目与产品之间多对多的矩阵式管理关系，既要满足项目管理的需要，又要满足各系统的产品管理的需要。一般的经验是，将针对单个系统的软件需求、设计、编码、测试的文档作为产品文档，作为相应的软件版本的配套文档，反映软件系统本身的变化过程，而将跨系统的业务需求、整体方案、联调测试、联合投产、项目管理等相关文档作为项目文档，作为与相应业务需求和项目的配套文档。这方面可以具体参考之前的短文《软件研发项目中业务需求与应用系统之间的矩阵化管理》。满足产品生命周期管理的需要就产品文档而言，有的文档可以是增量式的，只说明某一个版本的具体情况，而有的文档则需要是全量式的，需要随着新版本的发布而不断更新，保持与最新版本相一致，最典型的例子就是用户手册，通常都要随着版本的更新不断进行同步更新，对应旧版本的用户手册已经没有实用价值。另外像产品使用的FAQ这类文档，也是需要不断加以补充、更新，并且以全量版本的方式发布。同时，像系统技术架构、数据结构、发生变更的代码等，这些其实也需要维护全量的最新版本，才能有效支持后续版本的设计开发的需要。因此在文档管理中，也需要对文档进一步细分，同时满足