产品开发项目中文档的重要性

产品开发项目中文档的重要性

蒋小东

现在，很多人认为写文档是一件苦差使，特别是研发人员，觉得写文档是一种浪费，和产品开发工作没有太大关系，更愿意把写文档的时间用来写代码画图纸。

实际上，一个成功完整的产品开发项目，最终产出的不只是可交付的实际产品，还包括产品开发过程中的文档，以及产品开发的数据。文档在产品开发项目管理中非常重要，不只是产品的一个组成部分，而且还是产品开发项目的一种非常重要的管理工具。

文档是产品的重要组成部分，同时能得到很好的复用。一位著名的软件工程专家曾说过：只要提供完整的架构、需求与设计文档，在没有源代码的情况下，可以重新开发出一款与原来一样的产品。这段话非常有代表性，道出了文档的真正作用，因为这些文档是产品最系统最全面的反映，并且不依赖于具体的实现方式，哪怕这些文档针对的产品不复存在也能根据这些文档开发出同样的产品。再比如，很多开源项目的源代码和可运行的产品是免费的，但相关的设计文档和使用说明文档确实收费的，文档的重要性由此可见一斑。

文档是管理者跟踪和控制项目的一个重要工具。管理都跟踪和控制项目主要通过面对面的交流与文档两种方式，交流具有随机性、即时性与局限性的特点，而文档具有延续性、长期性与全面性的特点，特别是报告与进度文档能让管理者对项目的整体情况了如指掌。

文档在产品开发项目各角色之间起多种桥梁作用。研发人员在各个阶段中以文档作为前阶段工作成果的体现和后阶段工作的依据，这个作用是显而易见的。研发过程中研发人员需制定一些工作计划或工作报告，这些计划和报告都要提供给管理人员，并得到必要的支持。管理人员则可通过这些文档了解项目安排、进度、资源使用和成果等。研发人员需为用户了解系统的使用、操作和维护提供详细的资料即用户文档。

也许有人会说，编写和维护文档需要花费大量的时间和精力，并要配备相应的管理人员，这必然会增加公司的运营成本，从短期和单个项目来说确实是这样，

但从长远和一系列项目来看，其会带来降低成本、提高质量、提高项目管理水平、提高用户满意度等好处。因为一个项目中完整的流程、规范和经验可以很容易的复制到另一个新项目中，这其中就是有文档把项目的整个过程记录在案，而不是在人的脑袋里，这样就能在另一个项目中得到很好的复用。

写文档的本质是设计出问题的解决方案和规范项目管理。设计和直接写代码的区别是设计需要站在一个比写代码更高的层次上来看问题，当面对一个问题时，很可能另外的问题与之相关联(隐式地/显式地)，此时如果写分析设计文档，那么相当于充分全面地考虑这个问题，而直接写代码往往会让人沉溺于细节。由此可见编写必要的文档会使自己考虑问题更全面、更系统，是一种很好的习惯。

评审与修改文档比评审与修改具体的实现容易、简单。在进行系统的相关评审时，看一份架构文档或系统设计文档就能对系统的结构、系统的组成及系统的实现思路有一个全面的了解与认识，评审这样的文档则比想通过代码获得这些信息容易简单多了。从感情的角度来说，每一个开发工程师都对自己的代码有一种依恋感，害怕丢弃已有的代码和方案；而修改文档则会让这种感觉变得非常小。

谈了这么多，系统开发工程师肯定会振振有词的说：我觉得用代码来表达解决问题的方案比写文档更加方便和直接。就单个问题在很短的时间而言，这是一个站的住脚的理由——代码的字数肯定比文档的叙述要少得多，而且多数开发工程师的思维更加适应编程语言。但是如果涉及到多个问题或者几个系统模块，时间跨度是几个版本的时候，上面的理由多少显得有些苍白无力。

诚然，文档不是越多越好，要恰到好处。写一些质量差、脱离实际的文档，只会适得其反，写文档的人浪费了大量的时间和精力，看文档的人不知所云，故只有高质量的、必要的文档才是我们所需要的。

既然文档这么重要，一定有人会问：如何写好文档呢？这个就是接下来要谈的问题。

大家在写文档的时候，肯定会为从哪里写起、文档的结构怎么定、具体写哪些内容等发愁，这就需要企业建立起自己的组织过程资产库，提供模板和样例。文档模板规定了该类文档的组织结构、主要内容、模式要求等；样例提供文档编写的范例与参考。当然，文档的模板不是拍脑袋弄出来的，是来源于实际项目，并参考了业界的一些最佳作法，然后到具体项目中使用再修订最后才订搞，后续

不断优化改进；样例则是模板在实际产品开发项目中使用的结果。

再就是，组织过程资产库中发布的文档模板是比较全面和系统的，那么在一些实际项目中就会有自己的特点，可能不需要提供项目每个阶段所有的文档，可能编写的文档内容不需要包括文档模板中所有的内容，这种情况可以根据实际情况裁减，提供裁减指南。

随着信息技术的发展，项目中的很大一部分文档通过一些工具和管理系统反映出来，像一些建模工具、项目管理系统、需求管理系统等，但这些都是文档的另一种表现形式，很多编写的工作通过工具和系统自动化处理，从而很大程度上提高的编写文档的速度与质量，同时大大提高了效率。

不管如何，我们要意识到写文档的重要性和必要性，并养成编写好文档的习惯。

【本文档内容可以自由复制内容或自由编辑修改内容期待你的好评和关注，我们将会做得更好】