敏捷开发与文档：互补还是互斥？

如果敏捷是反文档的，为什么会发布一个宣言？

2001年，17位软件开发、测试人员（其中包括Ward Cunningham、Jim Highsmith、Alistair Cockburn以及Bob Martin）共同发布了《敏捷宣言》，并正式提出敏捷开发方法，作为传统文档驱动、重量级软件开发过程的替代方案。《宣言》提出了以下基本原则：

• 个人和交互高于过程和工具
• 工作软件胜过全面的文档
• 客户协作高于合同谈判
• 响应变化而不是遵循计划

似乎预见到这种简单可能会导致误解，《敏捷宣言》也对此进行了澄清：“也就是说，虽然右边的东西有价值，但我们更看重左边的东西。”

即便如此，业内对敏捷开发方法的误解和困惑仍然存在。“over”被“instead of”所取代，原本《敏捷宣言》的意图是“最好把更多的注意力放在软件上，而不是把时间花在过于详细的前期文档上”，现在似乎变成了“让我们完全抛弃文档，并希望我们记住讨论的所有事情。”

一、敏捷神话：“文档并不重要”

采用传统IT项目方法的团队会在项目的早期阶段定义并记录需求。随后，这些需求将会被提交给开发人员，开发人员收到需求后便立即开始实施。

虽然敏捷开发方法是作为这种文档驱动开发过程的替代方法而创建的，但它并不打算完全消除内部文档。由于软件开发在本质上是动态的，因此，敏捷开发更重视工作软件而非综合文档。

敏捷开发方法中没有任何内容会阻止团队创建项目所需的文档。事实上，在某些情况下，文档是绝对需要的：将用户故事添加到待办事项列表中，以及创建流程图、做会议记录等。敏捷只是——敏捷只是建议在这方面团队要聪明一点。

文档应该“刚刚好”。太多或过于全面的文档会浪费时间，而且开发人员很少相信详细的文档，因为它通常与实际代码不同步。另一方面，经验表明，文档太少始终是困扰沟通、学习和知识共享问题的根源。

二、投资敏捷文档的原因

敏捷文档的创建和维护对某些人来说是“不可避免的灾难”，但对另一些人来说，这是一项愉快的任务。同样，会有一些合理的理由让你相信，值得在敏捷文档上投入时间：

• 项目的利益相关者需要它。从根本上来说，创建文档是一个业务决策，团队将利益相关者的资源投入到文档开发中，因此他们应该对是否以这种方式花费他们的钱有发言权。
• 支持与外部团队的沟通。开发团队总是位于同一地点是不可能的，并且让利益相关者随时待命也是不可行的。共享文档通常是与偶尔的面对面讨论、电话会议、电子邮件和协作工具相结合的解决方案的一部分。
• 也不可能总是让项目涉众随时待命。共享文档通常与偶尔的面对面讨论、电话会议、电子邮件和协作工具结合在一起，是解决方案的一部分。
• 支持组织记忆。敏捷建模的原则之一是“实现下一个努力是你的次要目标”，这意味着与“工作软件是你的首要目标”的原则相平衡。这意味着，团队在开发软件时，还需要开发使用、操作、支持和维护软件所需的支持文档。
• 把事情想清楚。把想法写在纸上的行为可以帮助自己巩固它们，并发现自己思维方式中的问题。那些在脑海中看起来清晰而直接的东西，往往会被证明是非常复杂的，所以可以先把它写下来。

虽然以上所有的理由可能都是文档化的合理理由，但我们总是问自己这样一个问题：我们目前需要的最少可交付量是多少？

三、如何在敏捷中编写文档

1.敏捷文档的4条原则

• 敏捷中的文档是“可变的”，需要整个团队协同维护。为了充分利用我们在文档上投入的时间，我们可以遵循一些简单的原则：
• 确保它总是“刚刚好”。请记住，创建的任何文档都必须在之后进行维护。如果文档简单、不复杂、不太详细，就更容易理解和更新。
• 用“just in time”来写。在记录之前先耐心等待——这是避免积累错误和过时信息的最好方法。在需要的时候再生成文档，而不是在需要之前生成。
• 将文档放在一个容易获取的地方。文档只有在可访问的情况下才有用，将产品文档存储在团队成员可以轻松找到的地方。
• 与团队合作。在敏捷团队中维护文档是一个协作过程，应该鼓励每个团队成员对此做出贡献。

2.何时记录

敏捷中工作软件的迭代交付有效地取代了很多（尽管不是全部）全面的前期需求文档。其理念是尽可能保持文档的简单和轻量级，特别是在项目的早期阶段。那么在什么情况下值得在文档中投入时间呢？

一个常见的敏捷实践是尽可能推迟所有可交付文档的创建，在实际需要交付文档之前创建文档。例如，系统概述和支持文档最好在软件开发生命周期（SDLC）的结束时编写。从本质上讲，这种方法是在等到信息最终确定后再捕获它。
另一种敏捷文档的策略是持续文档化。在整个项目中编写可交付文档，在更新代码的同时更新文档。这种方法符合敏捷的方法，即持续生成潜在的可交付的解决方案。

然而，由于需求可能在项目的过程中不断发展，因此需要相当多的时间来让可交付文档的保持最新状态。从敏捷的角度来看，这又是一份“沉重的负担”。

在实践中，敏捷通常会推迟编写文档，直到他们有时间这样做，实际上，即使他们最初决定持续更新文档，也会逐渐转向文档的后期实践。

3.记录什么

• 敏捷文档中可能用到的文档示例包括案例研究、图表、表格和站点地图。以下是在项目过程中会考虑创建的一些文档：
• 产品愿景：它是对产品核心的描述，是对当前的成本估算、预期收益、风险、人员配备估算和计划里程碑的总结。这一文档的要求是：保持简短，直切要点。
• 项目概述：这是与项目相关的关键信息的总结，例如主要用户联系方式、技术和用于构建系统的工具等。将其作为团队新成员的起点，并在整个开发过程中对其进行维护。
• 设计决策：这是团队在整个项目中做出的与设计和架构相关的关键决策的概述。
• 操作文档：这通常是对系统所涉及的依赖项的描述，以及对备份过程的参考、故障排除指南等。运营部门可能会有此类文档的标准格式。
• 需求文档：它是对系统功能的概述，包括用例、用户故事或基本用户界面原型等。旨在将需求捕获为可执行规范。
• 支持文档：这包括专门为支持人员提供的培训材料、故障排除指南等。与运营部门一样，支持团队可能有标准模板或示例来使用。
• 系统文档：提供系统的概述，包括技术体系结构、业务体系结构和其他高级需求。系统文档有助于确保关键信息的留存。
• 用户文档：它包括用户参考手册和支持指南。这一文档的要求是保持简单、易懂。如果需要采用大量的培训来教会用户如何使用该产品，那么解决方案文档的设计就是有缺陷的。

四、结论

“我们接受文档，但不接受数百页从未维护过以及很少使用的大部头。”

敏捷开发方法绝不是反文档的。它只是提醒团队不要编写多余的文档，并且在必要时尽可能保持文档的简单性。通过敲定某种格式和细节级别的，允许更改并能交付足够价值的文档，以保持团队在正确的方向上前进。

*该文为翻译文章，原文链接：https://www.nuclino.com/articles/agile-documentation