敏捷中的文档：写多少、何时写?

        英文原文：Documentation in Agile: How Much and When to Write It?

        敏捷开发宣言强调“可以工作的软件胜过面面俱到的文档”。该核心价值要求我们去及思考要编写多少文档，需要编写什么类型的文档以及什么时候需要去编写文档。

        在 Jonathan Berger 的博文《最低限度交付物》一文中，提到关于在设计阶段的决策沟通。他对有关编写文档的观点如下：

敏捷宣言更喜欢“可以工作的软件胜过面面俱到的文档”，那么，为什么设计者还要花时间在用户将永不会看到的东西上？敏捷的目的是尽量减少浪费，所以 采取了极端的逻辑，所有的文档都是浪费的东西。这并不意味着文档可以（或应该）被完全抛弃掉。文档对于团队来说是有用的（特别是当团队要扩展规模时）。但 宣言建议，减少文档是一件好事，而设计者应该寻求利用最少量的文档沟通设计决策。

        Jonathan 针对如何尽量减少文档提供了如下建议:

        1) 在你的团队中普及“越少的东西会更好”的理念。

        2) 时刻思考这个问题：我们马上需要交付的最少量的交付物有哪些？

        Ashish Sharma 在《敏捷的本质、价值和及时的文档》一文中，提到如何在文档和讨论之间取得平衡：

敏捷的目标应该是在文档和讨论之间的适当平衡。文档是每个系统的重要组成部分。无论是否采用敏捷或其他方法，相当全面的文档并不能保证项目的成功。事实上，它会增加失败的机会。

        他提到当考虑要写多少文档和什么时候去编写的时候，可以参考下面三个标准：

必不可少：文档应该仅够用但详细。

有价值的：编写文的确所需要的文档，而不是我们想编写时才编写的文档。

及时：文档应该当我们需要的时候，以及时的方式（JIT）编写。

        Michael Nygard 描述了对文档相关流程的看法。他建议用一开始就考虑结果的方式去思考流程：

我经常发现很多流程都没有消费者。这纯粹就是浪费！从表面上看没人使用输出物，但过程的负责人根本没意识到。

        Michael 建议，流程包括它们的输入和输出都能从消费者的角度去描述。他分享了可以下面的问题去协助描述：

        谁是最终消费者？

        他们的需求是什么？

        你如何交付给他们？

        你如何知道他们如何准备好？

        你如何生产？

        你需要什么输入去生产产品？

        Tom de Lancey 于 2013 年早些时候在 LinkedIn 中开展的关于《紧急的文档：敏捷与瀑布模型的一个重要区别》中说道：

很多人对于放弃他们熟悉经常使用的文档感到不舒服：系统需求、系统设计、愿景和范围、用例、模式、工作流程图、Rational 统一过程文档等。很多人都不能将这些文档分拆成五个句子的故事。

        他描述了一种称为“紧急文档”的分析方法用于编写文档：

(…)我们不会浪费时间和精力在编写那些我们未曾发现如何去做的文档上。当我们发现问题的时候才编写文档。我们编写实际所需要的文档，而不是那些我们想去写的文档。

        TOM 说的紧急文档的其中一个好处是：

文档变成开发过程的一个部分，而不是单独的活动。因为文档实际上是十分有用的，整个团队都有兴趣去维护它。每一个用户故事都有单独的任务需要去更新 WIKI（使用一个将每个用户故事相互连接的 SharePoint 网站）。

        Mario Moreira 写了一篇关于《敏捷世界的正常文档规模》的博文。正如 Mario 说的，适当调整规模是对过去或现在有大量的文档的软件项目的响应：

文档的正常规模意味着，编写和维护文档的精力投入加上所写文档自身的价值，相比没有该文档（比如，重新组织信息的投入和没有文档对当前决策带来的影响），应该能获得更好地投资回报率，

        他的博文提供了在正常文档规模的建议。他的部分建议如下：

文档应当采取合作的性质。它不应只由一人编写得那么完美，而应该与他人分享。应当在草稿阶段就进行分享以获得足够的信息。

关注仅仅够好的文档并且避免太多的前期细节，因为那样意味着很多的猜测并且会浪费时间。仅仅够好意味着只针对当前所了解的编写文档。

文档应该以多种形式存在。不但只是 Word 格式的文档，还可以存在于 wiki、存在于敏捷工具，或代码中的注释或其他。

        各位是如何编写文档的？要编写多少和何时开始呢？欢迎讨论。