如何平衡文档需求和敏捷开发

Question

在我们的开发小组中，目前有关于敏捷和水方法的讨论。没有人对敏捷有任何实际经验，但我们正在阅读。

敏捷宣言列出了4个价值：

1. 过程和工具上的个人和交互
2. 基于综合文档的工作软件
3. 合同谈判中的客户协作
4. 响应按计划进行的变更

我们是一个内部开发集团，为我们企业其他单位的消费开发应用程序。一个由10个开发人员组成的团队同时构建和发布多个项目，通常每个项目上有一个--也许是2个(很少)的开发人员。

在我看来，从可支持性的角度来看，组织需要将一些真正的价值放在文档上--因为没有它，资源变化就会带来严重的风险。

在敏捷地支持交互和软件交付而不是过程和文档的情况下，如何平衡它与可支持系统的需求，以及维护对这些系统如何工作的知识和理解？

使用倾向于文档化的瀑布式方法(设计前的需求，施工前的设计规范)，很容易构建一个满足某些组织需求的流程--我们如何使用敏捷方法来实现这一点？

Answer 1

我不一定要说敏捷回避文档，而是回避预先的文档。这是为了解决这样一个问题:通过如此巨大的努力(a)最终与所创建的东西有很大的不同，因为业务需求的变化、范围的扩大等，或者(b)导致项目失败，因为交付取决于如此巨大的期望。

当然，在某些情况下，文档是必不可少的。我刚刚开始开发一个商业应用程序，为客户提供准确、最新的文档是必不可少的。团队也是敏捷的(scrum)。

在我们的例子中，我们有一个人(非开发人员)负责文档。

这很有帮助，但是还有更重要的组件。一种是将文档作为“完成的定义”的一部分。您可以从涉众那里获得每个特性的接受标准，但是附加到该特性文档的要求之后。第二个组件是将文档烘焙到流程中。它不能是可选的，它不能发生在“任何时候”。在我们的例子中，我们为文档人员演示了一个给定的特性，它是在涉众评审之后，在进入QA/测试之前为文档人员演示的。每次都是这样。如果您已经说过您的待办事项已经准备好进行测试，并且还没有提交文档，那么您就破坏了这个过程--就像破坏构建一样。

这更适合敏捷，因为您只是在记录成品中的实际内容。

我知道我们谈论的是不同类型的文档--你说的更多的是规格。最后一部分仍然适用--只记录你在产品中实际投入的内容。我还将添加一个技巧，您可以将单元测试创建为“可执行规范”，并让您的测试套件记录产品。您不一定需要实践TDD来实现这一点，但是如果您的团队还没有进行广泛的单元测试，那么这就是另一个完整的蜡球。

Answer 2

首先，在没有经验的情况下，小心地致力于敏捷--这是失败的最好方法。如果没有一个知道什么是敏捷以及它应该如何工作的团队，您就不想迁移到敏捷体验。我强烈建议，在您转向敏捷之前，至少要找到一条黑带，并将一半以上的团队送到敏捷培训中。

话虽如此，敏捷并没有说没有文档。它只是指出敏捷的过程，减少了对大量文档的需求。由于有一个更紧密的反馈循环，最终用户通常理解系统应该做什么。我从事过的大多数成功的敏捷项目都有某种类型的协作--wiki/工具--这确实是实时文档。开发人员/业务用户都为记录系统做出了积极的贡献，也就是说，您可以在您的故事中添加某种类型的系统概述。

根据我过去的经验，这40页的手册从来没有用过，或者只对超级技术人员有用。当你在浪费你最后三个星期的写作文档时，你错过了宝贵的几个星期的过渡期。更好的方法是指导他人，引导他们完成实时代码，帮助他们提供支持等等。

至于您的最后一点，敏捷并没有在需求之前进行设计，它只是表示在开始设计之前，您不需要完成所有的需求。

希望这能回答你的问题。

Answer 3

就我个人而言，我坚持每周的1/2天是一个文件日(通常是星期五)。虽然新的类/方法/属性应该在开发过程中被文档阻止，但这一额外的半天允许在API文档中进行注释，并在代码中进行注释。在允许继续进行代码开发之前，将对每一组新的注释进行同行评审，以确保团队的另一名成员能够理解该文档。

我发现，特别是在用新参数扩展方法时，这些方法通常不会添加到docblocks中，因此API很快就过时了……但这1/2天试图使它保持最新的状态。

我还一直在研究自动化进程，以确定docblock何时与方法定义不同步。

然后每个月有一天用于确保非API文档的维护.例如工作实例等。

如果这些“开销”天实际上是计划到sprint中，那么文档就不再是一个主要的问题了。