文档的力量

文档的力量

做软件开发要写文档，文档主要起的是一种说明性文字的作用，为了让用户很方便地使用你的软件，最起码要写一个用户手册，当然，有些软件不用写用户手册用户也会用，比如Windows自带的计算器，往往这类软件在用户点击帮助菜单后，弹出一个版权信息，这也算是一种文档吧。大多数软件都要比计算器之类的程序要复杂得多，所以用户手册一般是免不了要写的。

针对用户，要写帮助文档，针对软件开发过程，则要写开发文档，以往开发文档包含软件需求分析、概要设计、详细设计以及测试计划和测试报告等一大堆文档，所有这些文档作用都是要给开发人员提供信息来源和编码支持。随着软件开发规模越来越大，构建一个软件成本几乎和建造一栋楼的成本相当，在如此规模的软件开发过程中，正规而精确的文档的作用是非常关键的。

有很多程序员认识不到文档的重要性，特别是我们国内的程序员，我也是其中一员，我们通常认为编码是第一位的，结果是最重要的，要交给最终用户能够使用的东西才是王道。纠其原因，我想是和国内的软件开发环境有关，国内软件售价，往往价格偏低，因为价格低，所以管理人员就会压低成本，一部分是人员成本，一部分是时间成本。一方面人员不整，所以没有相关的文档编写人员，或者需要编写文档的主要设计人员忙于编码而忽视了文档，况且，一般编码人员，不管其水平多高，对于编写文档之类的活都是避而远之的。另一方面项目时间的紧迫性也使得开发人员缩短编写文档的时间，使得做出来的文档流于形式或者流于表面，根本起不到对开发工作的指导作用。更有一部分原因，由于形式主义、官僚主义盛行，文档成为那些政府机关项目用于向领导汇报的工具，造成的结果就是外行指挥内行，这些文档成为了肤皮潦草的报告。

我们没有力量改变这种情况，净化国内的开发环境需要时间，我们能做的就是认识到文档的重要性。举个例子，印度软件出口量全球第一，靠的是什么，国内有接触过印度软件源码的同行告诉我们，说印度的软件结构差，不好维护，效率低，代码写得乱七八糟，根本读不通顺。但有一样不得不让人敬佩的是，人家的文档写得非常全，写得非常棒！这就是文档对于一个糟糕项目的维护能力。还有一个例子就是微软，微软做开发的东西在早些时候完全搞不过其它一些公司的产品，像什么MFC、VB等，都搞不过Borland公司的同类产品，但是你看现在怎么样，Borland公司只能靠给微软维护Delphi度日。扯得有点远，造成这种情况的原因是微软的开放文档策略，微软提供多达几个G的开发文档供开发人员参考，同时还提供源码级的开发组件给合作伙伴，共同为用户开发产品。比如，微软提供VBA-SDK开发包以供软件开发商将自己的产品嵌入二次开发的能力，仅这一项就拉拢了像AutoDesk这一级别的战略合作伙伴，拉了一大帮公司。其它公司靠什么来竞争？

文档如此重要，正确地规划文档所要编写的内容就成了很重要的事。文档不仅要体现整个软件的结构，还要体现它的任何一部分细节的构建思路，要做到这一点，以往的做法就是做两个文档，一个是概要设计，一个是详细设计。同时，为了保证软件的质量，还需要写测试文档等。这种做法目前在大型项目上还是比较流行。

目前国际上流行一种新的软件开发流程，称为敏捷软件开发。该软件开发流程以全新的开发宗旨与理念给开发人员以耳目一新的感觉，敏捷开发的主要倡导者之一，具体名字忘了是谁了，提出了一个观点，一份过于详细的设计文档是腐朽无用的，真正有价值的文档是整洁流畅具备很高可读性的源代码。该大师指出了我们一些常见困惑的来源，即我们为什么不爱写设计文档，是因为我们写出来的文档价值不像最初所设想的那样，这些文档要么流于形式，要么与最终构建的软件大相径庭，我们有时不得不花费大量的时间来修改设计文档，使得文档与已经构建完成的软件相对应。大师说，编写完成的设计文档无法与变化无常的需求想适应，因此是腐朽的，唯一能快速响应变化的文档就是源代码，一份结构清晰，意义明确，带有适当注释的源代码就是一份很好的设计文档，这份文档必然要与变化的需求相适应的。这位前前辈也是倡导代码整洁(差不多就是代码口语化)的大师之一，从英语条度来看，他给出的规范的源代码读起来是非常通顺的，就像读一篇英语文档一样。目前中国人看的话，还是比较费劲，不如一份中文设计文档读起流畅。

除了设计文档外，软件开发过程中为了保证软件质量还需要做测试文档。在传统的软件开发流程中，在做完详细设计之后，就需要着手制订测试计划，最后测试完成之后，还要编写测试报告，这一块更容易变成表面工作，成为程序开发人员的负担，虽然测试文档同样非常重要。在当面对本身就具备腐臭气味的详细设计文档(大师语)时，根据它来制订的测试计划就更不能说得上是新鲜了。因此众多敏捷开发流程中出现了一种叫做测试驱动的开发流程，即在正式开发软件之前先要开发测试程序，在该测试程序的支持或者叫做监控下再来开发正式的软件。这无疑是一种比较极端的控制软件质量的方式，何时可以使用以及如何使用需要项目管理人员仔细斟酌。

总而言之，文档对于软件开发来说其重要性是不言而喻的，如何界定文档内容，如何规范文档内容，如何恰到好处地编写文档，更有力地为软件开发服务，就成了项目管理工作中最重要的一环，值得大家仔细地思量。