敏捷文档：雾里看花？

“可工作的软件胜过全面的文档。”2001 年的敏捷宣言如是说。

文档相关的主题在敏捷社区里面还是比较模糊吧？我们应该创建多少文档？哪些做法可行？哪些不行？关于文档，我们该如何从传统的流程切换到敏捷流程？是的，这个领域在敏捷社区中模糊不清。

最近在 Zen Agile 上有一篇帖子提出这样的问题：“要写多少文档才算足够？”作者谈及自己与政府部门的工作经历，并分析了他们重量级文档流程背后的原因：

曾有人告诉我：所有的文档都是必要的，“因为我们是政府”。深入一点之后，我发现如下原因： 1. 有了完整的信息，业务才能得以签字并批准开始构建。
2. 开发人员需要知道系统的设计目标。
3. 其他开发人员需要知道系统的构建方式，以做出改进。
4. 其他开发人员需要知道系统的构建方式，以进行维护。
5. 政府需要足够的信息来了解花钱的原因和方式。

在我的经验中，不管怎么样，业务中很少有人真正理解需求文档。他们想通过了解项目背景来确定当前的状态，以及项目的发起原因得到明确说明。也许他们会查看业务流程图，因为项目的图形说明要比用例更易于理解。不过总体看来，让他们签字通过批准没有见过的东西，这有点……呃……就是不太合逻辑。

博客文章接下来讲述了文档的一种变通方式，包括如下内容：

1. 以人物角色（personna）、场景和上下文图的方式明确阐述上下文。
2. 使用流程图和跟踪矩阵描述需求。
3. 使用数据模型、站点地图、导航设计和 UI 设计记录解决方案。
4. 使用原型验证解决方案。这里要签字，而且要反复签。
5. 记录系统构建，包括代码、测试方法和物理数据模型。

上面的流程已经过反复思索，而且来自实际经验。但是这跟我们在社区里的通用做法接近吗？

已经有很多关于用户故事、用例和以测试作为需求规范（tests as specification）的对话了。但是就只有这些了吗？已经有一本关于敏捷文档的书了，可在研究敏捷文档这个主题前，笔者从未听说过。其中有一章讲到起到唤醒记忆和表达作用的文档。甚至早在 3 年之前，InfoQ 就已经有一篇关于这个主题的新闻了。

关于文档，我们能否达成共识？甚至是否存在几个不同的“思想流派”？很难说，因为这个主题没有多少文字记录。也许它太简单了，因此没人记录。或者也许它太复杂了，推荐什么样的做法，我们也真的没有什么好主意。InfoQ 的好读者们？有什么想法吗？

查看英文原文： Agile Documentation: Is There Clarity?