理想中的文档
在瀑布式开发方式下，我们会接触如下几类文档：
| 名称 | 内容 | 目的 | 编写人员 |
|---|---|---|---|
| 需求说明 | 需求背景、目的、描述、指标 | 描述客户需求 | 需求分析人员 |
| 概要设计（系统设计） | 为实现需求而分解的软件模块以及之间的交互、接口、流程 | 将客户需求初步分解为软件需求 | 软件架构师 |
| 详细设计 | 对概要设计进行细节补充，如类图，异常流程 | 指导进一步编码 | 开发工程师 |
| 测试用例 | 按条目整理的测试场景和用例 | 指导测试执行 | 测试工程师 |
需求、测试、开发在各自的环节输出不同的文档，如果文档能将期望描述的内容准确无误的表述清楚，看起来也是一个能自圆其说的流程。
现实中的文档
理想虽然丰满，现实却往往骨感。在实际的软件开发活动中，理想中的文档面临着下面这些挑战：
- 软件开发活动高度抽象，客户需求往往又隐藏很多细节，用文字的形式描述清楚的的难度很大
- 写文档的人表达能力有限，软件开发行业绝大多数都是理工男（连理工女都很少），写文档本就是弱项
- 读文档的人对自己的理解能力总是莫名自信，即使文档没有说清楚，开发人员总是倾向于按照自己的理解去做
- 当需求或设计变更时，文档的更新往往不及时甚至是不更新
- 文档分散在多人的电脑中，即使作者自己及时更新了文档，也很难做到让所有人同步更新
文档所带来的沟通成本
编写文档的本意是为了在开发环节的各个阶段和角色之间传递信息，降低沟通的成本，而现实中文档到底有没有降低沟通成本呢？比如说下面这个场景，看着是不是觉得很眼熟：
- 测试人员发现了一个问题，于是提交一个bug
- 开发人员认为需求就是这么写的，不是bug，两边一通PK没有结果，找需求人员确认
- 需求分析人员之前没考虑到这个细节，于是重新定义了这个细节的处理方式，在他看来只需要稍作修改就可以了
- 开发人员分析当前的架构hold不住，于是只好重新推翻之前的代码再来一次
- 代码修改完毕，但设计文档忘记更新，代码和文档不同步
有丰富经验且善于总结经验的开发人员都知道 “细节是魔鬼” ，在我们依赖文档而不是更加 直接 和 实时 的方式进行沟通时，很有可能在沟通的环节我们就丢失了部分细节，到最后引入了额外的成本，有时候还是高额的成本。
可能有些同学会说，只要我们提升写文档的能力（比如金字塔）不就可以解决这个问题么？的确，理想情况下只要文档能够充分的体现作者的意图，覆盖所有的细节，那整个开发流程也没有问题，但现实情况是这很困难，这个领域是作家、写手才擅长的，技术人员能够往这个方向努力，个别技术人员也能达到比较高的水准，但很难让技术人员群体在整体上达到比较高的水准。而且文档还有其他的问题，我们继续往下看。
文档的价值有多大？
组织怎么看文档
CMM的流程定义和阶段产物能够给组织和公司带来安全感（特别是规模比较大，比较成熟的公司），看起来只要我们把各种文档写好，我们就能够得到一个可控的开发过程，项目的里程碑就能够按部就班的达成，另外，文字化后的知识也更加适合积累和扩散。
我见过很多项目经理确实是相信——只要我们输出了需求分析文档，那肯定是做了充分的需求分析的，只要我们输出了详细设计文档，那肯定是进行了全面的方案设计和评审，或者说，即使不是那么充分和全面，至少还是有在做，总比没有做要强。
一次实际的文档交付
印象最深的一次，为了实现一个非常明确的小需求，提交的文档有需求说明、需求分析、概要设计、详细设计、测试用例等好几份文档（这种非常明确的小型需求也会让开发人员直接进行需求分析），每一个文档都有固定模板，需要进行评审，提交评审记录并添加版本说明，而最后实际修改的代码不超过10行（还需要提交代码走查记录），这些文档最后会提交svn，然后就没有然后了，这些文档就这么安静的塞在一台不知道在哪的硬盘中，绝大多数的文档不会有人再重新打开看一眼，或者即使有人重新打开来看，文档内容和最新的代码已经完全没有任何联系了！
开发人员怎么看文档
以前看到过一个例子，大概意思是某监狱有一种惩罚犯人的方式，重复让犯人把砖块从A搬到B然后再从B搬到A，一直重复下去，犯人会在体力耗尽之前先精神崩溃。让开发人员反复从事于这些文档工作大概就是类似效果！
但是不要忘了，程序员可是这个世界上头脑最聪明的一拨人，碰到这种情况程序员会怎么处理？编呗！代码先写，程序先调，等所有事情做完了，不是要需求和设计文档吗，照着代码写呗，什么流程图、交互图，照着代码实现画呗，还要求评审记录和修改记录是吧，写的时候随便写几个错别字，故意留几个小章节先不写，等评审的时候就把这些录为评审记录嘛……所以，虽然理想的瀑布式开发模式下需求分析和设计以及评审要求在最前面，可是实际落地的时候呢，根本也不是那么回事！这种后补的文档既没有起到帮助分析需求的作用，也没有起到指导开发的作用，毫无价值可言，大家都知道是怎么回事，可偏偏还没有人说破，不仅仅是对这世界上最聪明头脑的浪费，还是对程序员良知的折磨，如果这不是反人类，那是什么？
文档还需不需要？
既然文档不能进行有效的沟通，也毫无价值可言，那我们是不是不需要文档了呢？很多刚刚转型敏捷的团队真的就会这么做，将所有的文档工作全部废弃，刚开始的时候觉得挺好，终于摆脱烦人的文档工作了，但是过一段时间之后又发现还是不行，不写文档的话很多事情无据可查，A 说我们当时说好了要按这个方式实现的，结果 B 说不对，明明是另一个方式，看起来没有文档也不行……
其实“需不需要写文档？”这个问题是个伪命题，文档肯定是需要的，即使是在敏捷宣言里面也没有否定文档的价值，真正的问题是“那些内容需要写文档？”
哪些内容需要些文档
原则很简单，看这个文档写出来之后将来有没有人会使用，如果有人确实需要这份文档，那文档就有存在的价值，比如下面这些：
- 需求背景，用户有什么业务痛点，需要什么软件功能
- 验收条件，满足哪些条件可以认为需求验收通过
- 接口说明，不同模块或者组件之间的接口定义
这些文档有明确的目标受众，知道自己的文档是写给谁看的，写起来就会有明确的针对性，哪些地方该细一点，哪些地方可以一笔带过，哪里需要结合图表，这些问题一旦弄清楚，文档的表意性就能提升一大步。
还有一些内容也需要文档化，比如团队的 DOD 定义，编码规范，可以帮助团队设定明确的目标和标准，再比如软件模块的概要设计说明，可以帮助团队新进成员快速理解代码，总之只要我们识别出文档存在的意义就OK。
文档的形式
文档应该放在所有人都能方便访问和同步修改的地方，目前我接触到比较好的方式是wiki，访问修改都很方便，能方便的进行comment并追踪wiki修改的历史记录，有的还能支持markingdown。
像word/pdf格式的文档，是直接保存在电脑硬盘上的，为了同步修改一般还需要放在 svn 上，不管是读还是写相对于wiki方式都困难的多。如果你所在的组织还要求对文档的读写进行权限控制，那基本上就没有几个人愿意看了。