敏捷文档:雾里看花?

  • Amr Elssamadisy
  • 郑柯

2010 年 3 月 23 日

话题:敏捷文化 & 方法

“可工作的软件胜过全面的文档。”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?

敏捷文化 & 方法