终结文档的噩梦——敏捷文档实践

前言

程序员最痛苦的几件事:1.别人不写文档,2.别人不写注释,3.我要写文档，4.我要写注释。这虽然是个笑话但也能看出开发人员对于文档的本能的抗拒。本文就结合作者的实践来介绍一下敏捷文档实践的几个思路。

似曾相识的故事

时间:项目验收ETA两周
地点：集中开发办公室
故事随之展开，突然接到通知下周要把所有交付物准备好，按照惯例除了系统本身外还有一些必要的文档，比如：使用手册，运维手册等。为了保险还是要求项目负责人核对了一下交付物列表，但噩耗就是在这时传来了。项目负责人说除了要交付使用和运维手册外还要交付全套的软件过程文档，即：《需求规格说明》，《概要设计》，《详细设计》，《确认测试计划》，《确认测试说明》，《确认测试报告》，相信了解的人应该知道这堆软件过程文档的编写绝不是轻松的事，留给我们的实践只有六天。
现在噩梦开始，我们马上纠集了除了处理紧急情况的全部有生力量(3.5人)投入到这些文档的编写，但稍微有一些软件工程经验的人应该心里都有数，稍微大一点的项目的需求，概设，详设都是什么规模的，少说也得80页，虽然有很多模板和死内容，但需求的用例图，概设的序列图和详设的类图都是必不可缺的，要想在六天内全部高质量的完成简直就是不可能。
于是为了交付，大家都懂的，虽然没有官方教程，各种技巧全部用上了，各种简化，各种复制粘贴，连续奋战了6天后，终于在最后截至时间前将文档发送了出去，但大家都不想再看那个文档，仿佛都做了个噩梦，都忘了刚刚都写了些什么东西。至于文档的质量大家只能呵呵一笑，更不要提跟系统的符合度等问题了。

如何终结这场噩梦

首先将项目负责人或经理抓住，搞清楚两件事：
1）为什么要把软件过程文档交付;
2）时间节点为什么不提前通知.
其次忽略上面的话，如何解决项目管理的问题已经超出了本文的讨论范围。我们要讨论的我们如何做才能结束这场关于软件过程文档的噩梦。
在能够结束之前我们搞清楚一个问题，为什么要写文档？

为什么要写过程文档

原因很简单，因为公司要求写，随之而来的就是为什么公司要求写文档？
1.为了公司的知识财产的传承，公司当然不希望再你离职后别人都无法理解之前的系统或项目。
2.为了规范软件开发流程，降低开发的风险，公司当然也不希望再上线的前一天才发现少做了界面或系统只能经受的了一个人操作。
但是再实际的项目中这些理由都有问题，下面是实际情况（针对普通民用领域）：
1.大部分文档都不能反映系统的设计和开发情况，在系统经过186次升级后你要是能保证文档的同步我真是服了。
2.大部分能够反映系统设计和开发情况的文档都是在项目完成后补充的。
在了解了困难和编写文档的目的后，我们可以通过调整过程文档的模式来达成公司的目的。我相信大部分公司都不会在意那堆文档上的样式的。

敏捷中的文档

其实相信有不少不了解敏捷的人会认为敏捷=不写文档不做设计，这其实有失偏差的，敏捷思维是强调的是做有价值的事，如果说文档是最后的交付物的话，那么敏捷团队一定会把完完整整的高质量的编写全部的文档来交付。
但事实是用户相对于超过200页冷冰冰的文档，更在乎能够使用的系统。因此敏捷团队更看重系统的开发和用户的反馈，至于文档投入的精力自然就少很多。
我们转向敏捷已经有3年多，这几年来比较重要文档：
1.系统原型界面
2.用户故事列表
3.架构设计
4.系统顶层数据流
5.系统接口
上面的每一个文档都事关系统成败，都要根据系统进展而同步更新，这样才能保证有效的系统交付到用户的手中。我们的目标是为用户创造价值，若高质量的文档价值很高那也要保证交付。

我们的实践

通过恰当的方法和适当的工具相结合我们可以将过程文档完成的更加高效和轻松。
下面我就列出传统的文档的实现方法。
1.《需求规格说明书》——动态的原型界面（若需要存档的可以打印处理）+用户故事地图（拍照打印）
2.《概要设计》——接口文档（RAP或swagger管理和导出）+数据流图+总体架构图（打印出来悬挂在开发环境中）
3.《详细设计》——html（通过javadoc自动生成，若要打印则需要搞个爬虫程序转成word）
4.《测试报告》——html（junit或testng生成的报告）+html（fitnesse来负责验收测试）
这里只列出我们验证过的一些经验，大家有建议也可以提。
对了文档生成代码这个事不太靠谱。。。。