粗略写了一下，感觉这个问题有两个方面具有一些有意思的地方：

1 他是一个非常典型的问题，在软件管理中，不能在其中走好平衡，就会出现大量问题；

2 他又是一个普通的管理中的平衡问题，在平衡上，往往无所谓对或者错，只有我们大家的认可。

把我的回信原封不动贴上去，做为一个记录吧……

 

Gaus:

好了，我忙完了手头的事情，乘着中午休息，我们开始讨论吧……

讨论的关键就是：什么是“足够的”？这儿讨论实际上就是一个“平衡”，过少的文档使得我们将来的工作无法进行，但是过多的文档，使得维护成为不可能，同时，过度的文档，有时候也会带来其他的问题。

首先，我们还是从我们在论坛上的观点起步：

我们只有在以下情况下，需要文档：

1 我们愿意和有能力维护的；

2 记录阶段的，而不是记录过程的；

3 是用户要求的，或者是为下一个阶段提供输入的；

 

第一个观点是来自于这样的认同，我们缺省认为，文档的抽象度高于代码。在一个项目中通过阅读代码来了解系统的成本非常高昂，而且事实上难以进行。所以我们需要文档来进行一个较高层次的抽象。在理想状态下，这个理由是对的，但是在实际情况下，这点并不是完全成立的。因为错误的文档，将给以后阅读的人带来难以想像的误导。通过这一点，我们可以知道，文档只有在正确的情况下，才能够满足较高抽象度的要求。所以，如果一个团队根本无意愿或者没有足够资源维护的文档，还不如不要；

 

第二：我们认为，文档之所以有必要存在，是为了给予他人阅读，并且他人通过阅读，可以较快得到整体的印象。所以我们只是需要记录状态的（目前是什么？）一般来说，我们并不是很关心，为什么现在是这样的，也许其中有很多变化的源头，但是至少在第一个阶段，我们并不需要他。所谓记录状态的，举个例子还说，rough design的文档，你不用展开说你为什么如此设计的，以及为什么改到现在的设计上。我关心的只是，现在是什么设计。文档中不要留下大量的修订信息，这会很大的干扰我的阅读；

 

第三：文档是需要花费大量成本的，比如根据我们的经验，一份言之有物的文档，一般来说，8个人时基本上只有2页左右的文档产出，而如此高的成本，我至少希望这份文档能够为下一个阶段产生输入，不然这份文档将无法维护。而且你几乎无法Final check，那么既然这份文档很可能本身就是错误的，那么还不如不要。比如事后来补充Detail design，除非你们将来很多后续的工作需要基于此展开（但是事实上，我并不这么认为，通过Rough design和自动生成的Java doc，一般来说已经差不多足够了，而且成本相对比较低），不然一般来说我不补充这份这么Detail的文档；

 

当然以上说的是项目本身的文档，项目管理文档需要更加小心，比如你的Project report，比如你的Release Plan等等。当然以上这些文档还是有必要存在的，因为他协调了项目组成员的脚步；对于这些文档，你需要有一个明确的概念：如果这些文档仅仅是我们自己使用，客户并不需要，也不关心，甚至这些文档就是一次性使用的东西，那么他提供的价值是否超过了他的成本？另外，我们是否没有更好的方式来进行？一般来说，我们认为，控制系统文档是为了解决沟通的问题，他主要在两个方面提供了价值：第一，他做为一个可以回溯的手段来提供沟通；第二他使得我们不会忘记很多事情。但是，对于小型团队来说，这两个理由就显得多少有点不那么充分了。比如如果我的团队就是5个人，大家工作地点都在一个办公室中，很方便沟通，那么为什么还需要很多控制文档呢？只有当面对面沟通成本高于维护一个文档的时候，你才有必要要很多控制序列文档。

 

OK，下面我们来看看几个不同的环境；

1 团队现状：混乱的团队？规范的团队？成熟的团队？

2 外围环境：是一个冻结的环境？还是快速变化的环境？

3 你们将主要由谁来使用这些文档？项目中？还是项目后？

 

首先，我定义一下以上两种环境，意味着什么，然后说几个典型的文档，在以上环境下的维护成本，和现实中，我们做到什么地步？

1 混乱的团队：基本上是一个哥们站起来喊一嗓子，说改！然后就开始了，SCM， Spec等等都谈不上管理；

2 规范的团队：基本上在SCM方面，在Requirement control和 test plan等等几个关键点上比较规范；

3 成熟的团队：基本上能够执行自动集成和自动化测试框架；是一个可以参考的标志；因为这涉及了很多范畴需要规范，不然执行Daily build和auto test基本上就是自己给自己找麻烦。

 

1 冻结的环境：需求在2个月内基本稳定（当然，在这两个月里面，你必须和客户还是有沟通的，而不是逃离客户的视线，来实行冻结）；在这种环境下，计划--控制的管理模式非常适合；

2 快速变化的环境：每周都会发生需求变更，甚至在项目后期也会发生频繁的需求变更；在这种环境下，计划--控制模式受到了挑战，因为过于细节的计划，过于细节的文档，都将面临边际收益急剧下降，而边际投入极速上升的境地；

 

OK，说明白了以上这些定义，我们该展开以下的一些文档的讨论了：我们挑选这样的几份关键文档：在项目本身的文档方面，我们选择Spec，design document, test case来说说事，我想基本上足够了。在控制文档上，我们选择project schedule, Project report, daily report来说事，基本上也差不多了。当然，如果你需要讨论其他的文档，可以提出来，我们个案讨论：

1 spec:一般的Spec，我们有两种写法，第一种是出流程，界面Demo，提出基本业务流程，然后列出主要的错误路径即中止，我们不会斤斤计较于在界面上输入某个字符，然后界面如何响应的问题；这种情况适合于快速需求变更，以及和客户之间沟通比较容易进行的情况下。因为这些细节问题，往往会在不断迭代过程中，不断提出，并且在研发过程中，和客户的逐点沟通来实现。先期企图稳定这些细节需求，后期成本提升很快（因为用户可能提出一个全局性的要求：比如所有字体用××字体，那么你的所有Use case将面临全部的更新）。当然，如果环境是一个冻结的环境，我们一般会把各种错误处理和错误机制都写进去，因为这将降低将来大家理解不同导致的潜在风险和个案沟通导致的问题。如果是一个混乱的团队，我们会倾向于把Spec做细，因为这时候潜在的风险变得很大，缺乏经验的工程师会使得很多低级错误不断重现，这样即使细的Spec维护成本很高，也还是值得的。但是对于经验丰富的工程师团队来说（比如我曾经带过一批经验在10年以上的工程师团队，在Spec方面的考虑就相对粗略一些，效果有时候会更好一些），就不必要这样了。当然，以上我们说的是，在项目中Spec的作用，如果在项目维护过程中，还需要Spec，那么我们常规来说，维护到流程一级，更细的层次是不维护的……如果需要更细节的内容，他们一般通过阅读代码来获得，而不是阅读文档（比如当某一个界面输入每一个字符都将进行一次判断等等），当然，一些关键点上的内容，还是有一定描述的（比如，用户的电话号码的格式等等，都会统一来描述）。一般一个15-30人月的小型项目，较为详细的Spec的规模可能在200-300页，维护成本一般在1.5-3倍规模。你可以自己计算一下成本；当然，这里首先需要说明的是：根据文档结构的好坏，维护的工作量相差非常大，极端情况下，几乎是数量级的工作量差别；

2 design：Design方面，我们一般有三种层次：第一个层次，基本类似于框架设计，设计出来Package的划分和固定接口协议就基本上结束了。第二个层次到Class级别，第三个层次是写到Function级别。这一点和上面很相似，我不展开说。一般来说，我们都做到第二层，因为使用了Rose进行了设计，从而使得设计的修改相对比较容易进行，所以这份文档基本上是维护的；但是如果是Word文档，一般来说是非常非常难以维护的，至少我没有看见真实有效的设计文档，大多数情况下，我情愿反向Java工程，然后在Rose中阅读来得更现实一些。使用Rose的情况下，文档工作量并不是很大，而且维护也相对简单。一般来说，如果建立一个基于User case的类级别设计的文档撰写和维护时间，一个15-30人月的项目中，不会超过80-120人时（当然仅仅是文档时间，而不包括你考虑时间）；

3 test case； 这又是很讨厌的一种，他基本上无法通过自动化系统来跟踪和维护，你必须手动维护其中Case设计的逻辑性。一般来说，如果是一个真正的Test case，在15-30人月的小型项目中，基本上会有300-400个测试用例；如果对于快速需求变化的情况，并且工程师相对很强，那么我们一般出到测试点设计阶段，只是针对测试重点展开成测试用例（因为那些测试用例将是需要很认真设计的），其他的就不展开了。当然了，如果你找了一帮啥也不懂的测试工程师，那么老老实实展开吧。维护成本在我的经验中，基本上是1.5-2倍之间。当然，如果你的系统是内在联系很多的情况下，而且变化快速，这将形成一个灾难。

 

我希望通过上面3个例子，说明白了我的意见：这取决于环境，将来阅读的人，和团队能力；不要问我应该做到什么地步？每个团队有自己的标准。至于给后面工程的文档，一般我们在Spec方面拿出Flow方面的内容，在部署方面，有System design doc（顺便说一句，这份文档几乎对于所有部署型项目来说，都是有必要存在的），设计方面，即使是Class的Rose图，基本上也足够了；Test case方面，后面的人员，基本上不关心，最多也就是看看系统风险点的获取上。另外不要去假设后面的人对系统一无所知，这样你的工作太难以展开了。我常规的一个假设是：他们接收系统的时候，我应该有一个工程师，会给予他们进行一次框架和功能方面的培训，并且能够支持他们1-2个月。如果你假设将来的人什么都不懂，那么很多事情成本将急剧上升。事实上，这是公司People Manager方面的范畴，如果一个项目组走得一个不剩，而没有一个人能够接手他们的工作，这是部门管理问题，不是项目管理范畴的内容。这是我的一个基本假设。

 

下面说控制文档：

schedule：对于良好的团队，Schedule会相对细节一些（指监控点会更多一些），对于弱的团队，Item会更多一些；对于变化快的部分，增加迭代计划次数；Schedule有必要存在，他一般来说，15-30人月的小型项目中，一个项目经理，每周需要花费2-8个小时来考虑和调节（至于修改时间，每周有个1-2小时，基本上就足够了），既然成本如此小，而且效果如此大，那么就有必要去做；

 

Project report:这对于项目本身产生的效果很小（当然不是说没有），平均一个项目经理每周会使用2-3小时去写这种文档；写risk, requirement status, task info, bug analysis, cost analysis, and so on. 但是这之所以是有价值的，是因为他提供了一个反思的渠道给项目经理；发现以前没有发现的问题，其次，他是项目经理申请资源，和公司正常运行所必须使用的润滑剂，所以即使耗费的成本，也是必须的；

 

但是daily report之类的文档，首先你要的是什么？如果仅仅是知道大家的进展，一般我不通过这种方法，因为有Checkpoint的监控，你在report中写的很多“完成10%-20%”，对我毫无价值。如果某一个Item可以细分，那么我就应该在schedule来细分，而不是需要定期汇报；其次，希望你反馈问题，方便我的排解。我觉得，如果你碰到问题了，不应该在文档里面告诉我，而是应该直接来找我，我来帮助排解。问题需要在第一时间被排掉，而不是这样拖着。那么最后的一点就是：你做了一些事情，对于我们很关键，我希望这些事情我能够知道。什么时候有这种情况呢？出差，和客户的沟通等等才有必要。所以，我一般仅仅要求外出出差的人撰写DR，其他人就算了。

 

通过上面三个过程的例子，希望我说明了我的意思：

对于控制文档来说，是否有必要，看成本，看效果，看是否有其他方式。如果有，就不用（因为事后这种文档根本没有人关心），如果没有更好的方式，文档就有必要。

 

gaus：对于以上的论述，我希望说明白了我的观点。就是初步指出了影响平衡点的因素，和如何在这些因素影响下，给出几个例子的平衡点选择。

不知道对你是否有用。希望看见你的观点。