语言 Chinese, Simplified

SEO Title

agilemodeling： Agile/Lean Documentation: Strategies for Agile Software Development

当我最初开始研究敏捷建模（AM）时，我想只关注有效建模的原则和实践，但很快发现这个范围还不够，我还需要考虑如何在创建时有效的问题。维护文档也是如此。一些敏捷模型将“演变”为官方系统文档，尽管绝大多数都不会，因此讨论如何敏捷这样做是相关的。本文探讨了IT组织内部文档的敏捷和精益理念。

在本文中，我将讨论以下主题：

关键点
模型，文档和源代码
为什么人们记录？
文档和项目成功之间的关系是什么？
模型什么时候成为永久性的？
与文档相关的问题是什么？
轻装旅行意味着什么？
什么时候文件敏捷？
你需要什么类型的文件？
敏捷专家是否真的在创建文档并且它有用吗？
什么时候应该创建文档？
什么时候应该更新文档？
有效的交接
模板有帮助吗？
如何减少文档CRUFT？
文档何时是最佳选择？
提高文档敏捷性的最佳实践

1.关键点

根本问题是沟通，而不是文件。
如果这是实现相关目标的最佳方式，敏捷专家会编写文档，但通常证明比编写静态文档更好的方法来实现这些目标。
记录稳定的东西，而不是投机的东西。
采用渐进的方法进行文档编制，寻求并定期对反馈采取行动。
优先考虑可执行的工作产品，例如客户测试和开发人员测试，而不是静态工作产品，例如普通旧文档（POD）。
您应该了解文档的总体拥有成本（TCO），并且必须明确选择进行该投资。
编写良好的文档可以有效地支持组织内存，但在项目期间进行通信的方式很差。
文档应简明扼要：概述/路线图通常比详细文档更受欢迎。
通过高质量的源代码和备份测试套件，您需要的系统文档要少得多。
尽可能轻装上阵
文档应该刚刚好。
综合文档并不能确保项目成功，事实上，它会增加失败的可能性。
模型不一定是文档，文档不一定是模型。
文档与源代码一样是系统的一部分。
您的团队的主要目标是开发软件，其次要目标是实现您的下一步工作。
拥有文档的好处必须大于创建和维护文档的成本。
开发人员很少信任文档，特别是详细的文档，因为它通常与代码不同步。
每个系统都有自己独特的文档需求，一个大小并不适合所有。
询问您是否需要文档，而不是您是否想要它。
对系统文档的投资是业务决策，而不是技术决策。
只有在生命周期中的适当位置需要时才创建文档。
仅在受伤时更新文档。

2.模型，文档和源代码

让我们首先理解模型，文档，源代码和文档之间的关系，如图1所示。从AM的角度来看，文档是源代码外部的任何工件，其目的是以持久的方式传递信息。这与模型的概念不同，模型是描述问题的一个或多个方面或解决问题的潜在解决方案的抽象。有些模型将成为文档，或作为其中的一部分包含在内，尽管在完成其目的后，更多的模型将被丢弃。一些模型将用于推动源代码的开发，尽管某些模型可能仅仅用于推动其他模型的开发。源代码是一系列指令，包括描述这些指令的注释，用于计算机系统。虽然源代码显然是一个抽象，尽管是一个详细的抽象，但在AM的范围内，它不会被视为模型，因为我想区分这两个概念。此外，为了便于讨论，术语文档包括源代码中的文档和注释。
敏捷建模

图1.模型，文档，源代码和文档之间的关系。

3.为什么人们会记录？

敏捷开发人员认识到文档是任何系统的固有部分，其创建和维护对某些人来说是“必要的邪恶”，对于其他人来说是一项令人愉快的任务，软件开发的一个方面可以在您选择这样做时变得敏捷。。创建文档有几个正当理由：

您的项目利益相关者需要它创建文档基本上是一项业务决策，您正在将项目利益相关者的资源投入到文档的开发中，因此他们应该最终决定他们的资金是用这种方式而不是技术方式。如果您的项目利益相关者可能会根据您的建议请求您提供的文档，并了解所涉及的权衡（稍后将详细介绍），那么您必须创建该文档。值得注意的是，eXtreme Programming（XP）非常明确地将文档作为业务决策。您应该只在项目利益相关者要求时创建文档？你说的荒谬！嗯，我的经验是，这不是荒谬的。您的项目利益相关者包括各种各样的人，包括您系统的所有客户，因此他们应该有一个相当不错的想法。维护开发人员或代表他们的人（如果他们尚未到位）将请求系统概述文档。用户及其管理层可能会要求用户提供文档。操作人员将要求操作文档。是的，您需要与他们密切合作以确定他们实际需要什么，有人将不得不决定为文档的开发和后续维护付费，您甚至可能需要解释所请求内容的含义，但这是可行的。
定义合同模型。合同模型定义了您的系统和外部系统如何相互交互，一些交互是双向的，而另一些是单向的，使得交互明确地涉及到每个人。当外部组控制系统所需的信息资源（例如数据库，遗留应用程序或信息服务）时，通常需要合同模型。 AM实践正式化合同模型表明，合同模型是双方应在必要时双方同意，记录和变更的内容。重要的是要理解合同模型的开发仍应由您的项目利益相关者进行验证 - 这是您花费的资金，如果他们选择冒险并且没有合同模型，那么这就是他们的选择。
支持与外部组的通信。并不总是能够共同定位开发团队，并且总是不可能让项目利益相关者（或者至少是当时需要的人）可用。当您需要与外部人员一起工作时，您需要找到与他们沟通的方式，共享文档通常是解决方案的一部分，并与偶尔的面对面讨论，电话会议，电子邮件和协作工具相结合。使用文档作为主要的沟通方式是错误的，因为它很容易误解已编写的内容，但它是一种很好的支持机制。在这种情况下考虑文档的好方法是，它是您最后的选择。请注意，这实际上是将模型传达到文档领域的扩展。
支持组织记忆。敏捷建模的原则之一是启用下一个努力是您的次要目标，这意味着作为主要目标的原则工作软件的平衡。一个重要的含义是我们不仅需要开发软件，而且我们还需要开发随着时间的推移使用，操作，支持和维护软件所需的支持文档。
用于审计目的。我曾在我们开发生命关键系统的组织工作，这些系统属于美国食品和药物管理局（FDA）审计指南的主持。我还曾在Sarbanes-Oxley（SOX或Sarbox）和/或BASEL-II适用的组织工作过。共同的主题是我们必须遵循已定义的流程并捕获我们这样做的证据，从而产生比我们通常编写的更多的文档。在这些情况下，您仍然希望创建足够的文档来完成工作。我看到的一个常见错误就是官僚们跳过“我们可能会被某某人审核，因此我们需要制作以下文件......”。我的建议是自己阅读适当的指导原则，因为它们很少需要官僚认为需要的指导原则。善于遵守法规。
想清楚某事。许多人编写文档，要么是为了亲自验证他们刚刚参与的一些团队工作，要么只是为了增加自己的理解。写作的过程，把你的想法写在纸上，可以帮助你巩固它们，发现你思维中的问题。一旦你试图详细地描述它，你脑海中出现的清晰而直接的东西往往会被证明是非常复杂的，而且你通常可以从先把它写下来中获益。正是出于这个原因，我建议人们在编写代码之前先写注释，这是我多年来一直遵循的做法。

您的涉众必须理解文档的总体拥有成本(TCO)，并且您的涉众必须明确决定对该文档进行投资。

这很可能与您以前的做法不同，这是有道理的，因为我在谈论如何在您的文档方法中变得更加敏捷。为什么这会有所不同，为什么它更敏捷？我的经验是，非敏捷环境中的开发人员往往被迫以不太理想的理由创建文档，通常基于政治原因，有时由于纯粹的无知，因此可能不会被允许尽可能有效。能够。创建文档以及如何打击文档的可疑原因包括：

希望看到请求者处于控制之中。人们将要求他们签署的文件，例如规范和详细的架构文档，并说“是的，继续并为我们建立其中一个。”每当我发现自己处于这种情况时，我会要求提供文件的个人是否也希望被视为对项目失败负责，因为开发团队太忙于关注不必要的文档而不是构建软件。然后，我建议他们不应该请求文档，而应该请求访问软件本身，即使它只是软件的内部版本，因此他们可以提供有关它的建设性反馈。他们仍然可以被视为项目的积极参与者，并且可以以富有成效的方式这样做。
请求者错误地认为文档与项目成功有关。没有东西会离事实很远。
请求者想证明他们存在的合理性。这种情况通常发生在那些“死木”的人迫切希望看到做某事的时候。这是一个阴险的问题，因为请求者通常表面上看起来是请求文档的一个很好的理由，这是他们多年来一直在做的事情，管理层通常认为这是必要的。为了解决这个问题，我会问请求者他们打算对文档做什么，他们为什么需要它，为什么为他们创建文档比我的团队需要做的其他工作更重要，等等，试图确定实际他们正在做的事情的价值。这些是有待提出的有效问题，虽然对于那些对开发工作没有太大价值的人来说是不舒服的。
请求者不知道更好。许多人一直在多年来一直关注非敏捷流程的组织中工作，可能以文档为中心的流程，在整个流程中生成大量文档以供审阅的流程，最后是软件。这是他们习惯的，所以他们只是在问你过去曾经得过的东西。您可以在项目早期生成软件的想法，这是您的主要目标，对许多人来说是新的，而且往往是激进的。
您的流程说创建文档。虽然这不是敏捷软件过程的问题，但它肯定可以与规范的软件过程一起使用。造成这一问题的最常见原因包括人们想要证明其存在（见上文），人们不了解软件开发过程或至少是他们所要求的含义，以及主要目标是花费数小时反对的情况有效地开发软件。再一次，解决这个问题的最佳策略是探索文档的创建是否真正为您的工作提供了价值。
有人想要保证一切都好。您的项目利益相关者正在为您的项目团队投入大量资源，他们会对您承担风险，并且他们希望知道他们的投资得到了充分利用。为了得到这种保证，他们可能会要求您提供文档，状态报告或概述文档，而不是理解您需要花时间远离您开发软件的真正目标，而不是意识到更好的请求是查看软件本身（如前所述，他们不知道更好）。您需要认识到您的项目利益相关者何时寻求保证，如果他们不信任您的团队，则在项目开始时常见，并找到提供该保证的替代方法。
您正在为另一个组指定工作。虽然我已经将这种情况确定为AM可能不合适的情况，但它仍然是证明创建大量文档的合理证据。文档是一种沟通方式，但它不是最好的方式。尝试寻找替代方法，例如偶尔与其他小组会面或使用协作工具，以减少对文档的依赖。
您的开发合同通常会重新竞争。这个问题在为政府机构工作的公司中普遍存在，尽管如果他们不履行，企业通常会威胁他们的承包商再次投标。所以呢？如果您的主要目标是开发软件，那么请专注于这样做，并且您更有可能充分履行合同。在这种情况下，直接客户经常在误导的情况下运作，即如果您不执行，他们可以将您生成的文档提供给下一个将从那里开始的承包商。在我看来，这与妄想有关。如果你做的那么糟糕，以至于你失去了合同的机会非常好，你也做了不好的文件，因此下一个承包商将需要重做它。即使您已经完成了文档的完美工作，但仍然失去了合同，下一个承包商很可能会拥有不同技能和足够时间的人，他们无论如何都需要重新审视这些要求。无论你怎么看，下一个承包商都不太可能利用你制作的文档。

我不相信圣诞老人，也不相信程序员会保持最新的外部文档。四十年的经验表明，这种特殊的教条充其量只是幻想。

4.文档与项目成功之间的关系是什么？

项目成功与编写综合文档之间没有牢固的关系，事实上，您编写的文档越多，项目失败的可能性就越大。您是否曾见过项目团队撰写全面的需求文档，让您的利益相关者签署该文档，只是让开发人员构建其他内容？或者团队实际建立规范，只是让你的利益相关者说这不是他们想要的？或者团队提供延迟或超预算，即使项目的大部分内容都很好看？你有没有见过一个团队创建一个全面的架构模型，让它被真正聪明的人审查和接受，只是看到架构在实践中失败了？或者开发人员只是忽略模型，然后以他们想要的方式构建它？您是否已经在管理层监督的幌子下看到了所有这一切，没有管理层意识到发生了什么直到它发生很久？图2取自我的文章“检查前线的大要求（BRUF）方法”，它探讨了写作的有效性项目生命周期早期的详细需求规范。正如您所看到的，似乎传统的需求方法似乎会使您的项目面临风险，至少在考虑投资回报率（ROI）的情况下。
敏捷文档
图2：串行方法对需求的有效性。

为什么人们错误地认为文档是软件开发的关键成功因素？我的理论是，在20世纪70年代和80年代，许多组织将他们的IT部门从“代码和修复”黑客心态转移到文档密集的串行瀑布流程。当他们这样做时，他们的成功率实际上提高了我们今天甚至用CMM / CMMI看到了这一点 - 当您从代码移动并将CMM（I）级别1修改为级别2或3时，即使您添加了更多文档开发，您实际上也看到了生产力的提高到你的过程。他们“学会”文档改进了软件开发工作，并对答案感到满意。那真是太不幸了。

CMM（I）的支持者，或其他不可避免地最终导致文档沉重的策略似乎从未提出过是否有更好的工作方式的问题。不会把精力集中在编写高质量的软件（例如测试驱动的开发实际上产生可执行的规范）上提供比编写文档更大的回报吗？难道找不到保持高质量代码（例如重构）的方法比编写文档提供更大的回报吗？文档的真正价值不在于增加对问题域的理解，还是在架构/设计的情况下增加对解决方案域的理解，而不是文档本身？如果是这样，也许只关注建模工作（例如敏捷模型驱动开发）而不是编写文档是一个更好的策略？

5.模型何时成为永久性的？

从表面上看，敏捷模型的生命周期非常简单 - 图3描绘了模型的高级UML状态机器图。模型将从一个想法开始 - “我们需要了解我们将如何构建这个”，“用户如何希望这样做”，或者“我们需要展示我们将要提供的内容” - 你要么选择建模要么放弃（为了我们的讨论，你选择执行的任何活动而不是建模都算作放弃）。该模型开始是暂时的，一旦它实现了它的直接目的，你打算抛弃它，这是敏捷开发人员创建的绝大多数模型的典型命运。这些模型通常是手绘草图，一旦将想法传达给目标受众，就会丢弃这些草图。您可以根据需要自然更新临时模型，经常创建它们，处理它们，然后在短时间内丢弃它们：许多敏捷模型在几分钟内创建为两三个人，以促进他们的讨论，而其他敏捷模型是在几个小时的时间内在几个人的建模会话中创建的。图3中描述的有趣转换是当您决定保留一个临时模型，使其永久化时，使其成为项目团队的官方文档之一。当满足以下所有条件时，临时模型将成为“守护者”：

将其永久化是一个明确而有价值的理由。
有模型提供价值的观众。
您的项目利益相关者愿意投入将其纳入文档。

图3.敏捷模型的生命周期。

Agile Model Lifecycle

点＃1和＃2由原则模型驱动有目的：您应该有一个有效的理由来创建模型，但您的文档也应该有明确的目的。您应该知道您为谁创建文档 - 可能是您的开发团队的子组，您的用户，或者在您发布系统后将维护和操作系统的团队 - 以及他们从该文档中需要的内容。基本思想是文档的创建和维护是开发团队的负担，如果您想增加某人的负担，您应该能够证明原因。这很简单。文档是一种负担，当人们认识到这个简单的事实时，他们会把自己放在一个明显更好的位置来适当地考虑它。是的，有效的文档可以为您的项目团队和项目利益相关者带来显着的好处，并且最大化利益相关者ROI的原则告诉您，好处应该超过团队负担的增加。重要的是要注意，除了经历成本的人之外，其他人有时会收到这些好处，例如，您的开发团队会受到维护开发人员受益的创建系统文档的成本的影响。这意味着，当您考虑文档的成本和收益时，您需要查看整个图片，其权衡取决于与文档相关的问题是什么？部分。第3点也是由最大化利益相关者投资回报率的原则和这样一个概念所驱动的，因为正是您所投资的项目利益相关者的资源应该是指导这些资源投资的方式，无论好坏。

正如您在图3中看到的那样，您可以重新考虑关于使模型永久化的决定，通常是因为您意识到模型提供的好处远远低于维护模型的负担。当这种情况发生时，模型要么被彻底丢弃，要么更常见的是该模型的所有者只是停止更新它并开始“聚集尘埃”。有时，如果系统被重写，开发团队，维护团队或“重新开发团队”会在数月或数年后恢复这些模型。这些停滞的模型经常被审查，被认为是显着过时的，然后被丢弃或用作模板，从中创建模型的新版本。理想情况下，这个新版本比原始版本更精简，因为如果原始模型没有为您的工作提供正面价值，那么遵循相同方法的更新版本可能也不会提供价值。在提高文档敏捷性的策略部分中讨论了这样做的技巧。

6.与文档相关的问题是什么？

敏捷开发人员认识到有效的文档是一种平衡行为，目标是在恰当的时间为恰当的受众提供足够的文档。为此，您必须解决以下问题：

软件开发与文档开发。这是您需要解决的基本问题 - 创建文档所花费的时间是花费时间而不是为用户开发新功能。一方面是没有编写任何文档的项目，而另一方面根本没有编写任何软件，也没有极端可能适合您的情况。请记住，您的主要目标是制作可运行的软件 - 您希望支持您的用户业务活动，您希望为您的组织创造收入，您希望收到有关您工作的反馈，您希望向您的用户证明您可以生产 - 但是你需要用你的次要目标来抵消这一点，这是为了实现下一步的努力。因此，您仍然需要编写一些文档（用户手册，操作手册，系统概述......）。
可执行规范提供的价值远远超过静态文档。可执行规范，例如指定大部分需求的客户测试套件，或指定详细设计的开发人员测试套件，为开发人员提供了重要价值，因为他们不仅指定了您的系统，还有助于验证它。由于这些工件增加了价值，因此开发人员保持最新状态的可能性要大得多。是的，您仍然需要一些静态文档，因为测试肯定不能满足您的整个文档需求，但您可以在哪里开发可执行的规范。
软件开发人员有知识，技术作家有技能。喜欢与否，很少有技术人员具有良好的写作技巧，只是因为他们没有花时间去获得他们的简单原因。问题是，适合编写文档的最佳人选是知道正在编写的主题的人，在本例中是系统的开发人员。许多团队只需将系统或其中的一部分交给技术作家，并要求他们“弄清楚”。这样做的好处是可以最大限度地减少开发人员的工作量，但会增加技术作者所需的工作量并增加他们弄错的可能性。更好的方法是让开发人员编写初始版本的文档，然后将其交给技术作者进行清理。这样做的好处是它可能更有效，开发人员进行“知识转储”，技术作者重构材料以有效地呈现它，但缺点是开发人员可能不知道如何开始甚至写什么关于。第三种方法，在我看来最好的方法是让技术作者和开发人员一起编写文档，在他们这样做时相互学习。
开发过程中所需要的通常与开发后所需的不同。在开发过程中，您有不同于开发后的需求 - 为了讨论开发后的活动，包括将发布版本转换为生产版本以及发布版本投入生产时的过渡期和生产阶段。企业统一流程。在开发过程中，您正在探索问题和解决方案空间，尝试了解您需要构建什么以及如何协同工作。在开发后，您希望了解构建的内容，为何以这种方式构建，以及如何操作它。此外，在开发过程中，您更愿意容忍粗略的草稿，草图和更大的不一致 - 毕竟这是您自己的工作 - 而在开发后您通常需要更正式的文档。最后，在开发过程中，您可能需要更少的文档，您更喜欢轻松旅行，而不是在开发后期间。
你在工作或完成时记录了吗？一个极端是与开发软件并行编写所有文档。优点是您在进步时捕获相关信息，但缺点是随着软件的发展，在重构时，您还需要重新编写文档。这不仅会降低您的开发工作速度，还会导致浪费精力 - 您昨天编写的文档需要在今天重写或丢弃，实际上这种方法不再适用于您。当您的需求尚未稳定时，当您采用迭代方法进行开发时，过多的文档可能会变得非常昂贵，因为您不断更新它以反映更改。另一个极端是等到你完成然后编写文档，主要的好处是你正在写一个已知的和稳定的东西（你刚刚构建的软件的发布）。这种方法显然有几个缺点。您可能已经忘记了您做出的决定背后的一些原因，您可能没有合适的人来编写文档，您可能没有资金来完成工作，或者编写文档的意愿可能不再存在。一个有效的中间立场是在整个项目稳定时捕获信息。
你能等到信息稳定下来吗？如果您编写的文档包含尚未稳定的信息，那么一旦信息发生变化，您就有可能需要重新编写文档。换句话说，您不希望投入大量时间来记录项目早期的需求或设计等推测性想法。相反，等到生命周期的后期，当信息稳定并且您知道哪些信息对您有用时。这意味着您的文档工作可能会在您的软件开发工作背后进行一些迭代。
代码文档与外部文档。您是否将所有文档放在代码中，是否编写了“自我记录”代码，或者将所有文档放在外部工件中？再次，你需要找到一个有效的中间立场。当您的受众是开发人员时，放置大部分文档的最佳位置是源代码。是的，您可能还需要一个针对该组的系统概述文档，但实际情况是这些人不会信任，更不用说阅读代码之外的文档 - 如果他们真的很聪明他们就不会信任代码中的文档。但是，文档的受众比开发人员要广泛得多。您可能需要为无法访问源代码的人员编写文档，或者至少无法理解它，例如用户，高级管理人员和操作人员。这些受众需要编写外部文档以满足其确切需求。 AM实践单一来源信息表明，您努力在尽可能最好的地方捕获一次信息。这通常在源代码或验收测试中。简而言之，努力使用尽可能最好的方法捕获和传递信息。
项目级与企业级文档。并非您编写的所有文档都将专门针对您的项目团队，或者是团队接管您的系统，其中一些可能需要在企业级别提供。您应该利用现有工件，包括但不限于组织内的系统文档和模型。这可能包括业务规则的现有定义，遗留系统的现有接口及其文档（有效的现有合同模型），描述整个公司数据资源的企业元数据存储库或企业业务模型。这些资源来自哪里？源信息来自其他项目团队，例如您的项目团队，可能由专家团队管理。是的，这显然是一种可能会促使不必要的官僚机构仍然可能变得敏捷的情况 - 集中管理团队需要找到一种有效地与您合作的方式。在开发过程中，他们应该提供您需要的现有模型和元数据等资源，并在需要帮助理解和使用这些资源时充当顾问。开发后，它们应该帮助您捕获相关信息以反馈到共享企业资源中，例如，将系统转换为生产的过程的一部分可能是确保对公司业务规则和元数据存储库进行更新。集中管理团队需要以客户为中心，真正实现敏捷，必须为他们的工作提供真正的商业价值，并积极努力了解他们管理的资源如何以及为何被客户使用。
数量与质量。基本的权衡是让文件违背你对其准确性的信任的“安全性”。您更愿意拥有2000页的系统文档，其中可能存在大量错误，但重要细节还是20页的高级概述？大文档很可能拥有维护和增强系统所需的大部分信息，但您是否相信其中包含的信息？较短的文档很可能不会包含您需要的详细信息，但它会提供您可以深入了解源代码或其他文档的地图，以获取详细信息。您更有可能信任这个文档，因为它更短，最糟糕的情况是您可以轻松更新或只是重写它，如果您发现它非常不准确，并且因为它处理高级概念，如您的系统架构将改变比较大的文件中包含的详细细节更慢。重要的是要理解我并不是说较大的文档质量自动低于较短的文档，但我说它很可能被认为是这样，直到证明不是这样。

记录稳定的东西，
不是投机的东西。

7.旅行灯意味着什么？

人们对旅行灯概念的最大误解之一就是它意味着你不会创造任何文件。现实是，没有什么能比真相更进一步。至少在上下文中，行车灯的意思是，您可以创建足够的模型和足够的文档来获取。在极少数情况下，这可能意味着您无需创建任何模型，可能是在一个非常小的项目上，甚至是没有文档，也许是在一个非常小的项目上。但是对于绝大多数项目，您需要创建一些模型和一些文档。

你怎么能确保自己轻装上阵？一个好的经验法则是你不应该在你真正需要它之前创建一个模型或文档 - 过早创建任何一个东西会让你有浪费时间去做你实际上不需要的东西的风险。我曾经在一个商业软件系统上工作，一个组织可以购买和安装开箱即用，或者更典型的是购买，然后让我工作的公司修改它以满足他们的确切需求。有一天，我们的销售人员在一家想要我们系统的公司上取得了新的领先优势，但这家公司还处于一个我们还没有经验的新领域。我们认为我们将要进行此次销售，我们最终确实得到了它，所以在我们自己与客户见面之前，其他几个人开始对我们认为需要做出的预期变化进行建模。经过几天的建模会议，我们得出的结论是变化很容易，毕竟我们的系统很棒，而且我们支持这个新客户端也没有问题。然后我们与他们交谈。在我们发现的七十多个新要求中，我们已经得到了大约一半的正确，不错，考虑到我们不知道我们在谈论什么，但我们已经错过了其他几百个。当然，我们基于我们错误要求的模型价值不大，我们不得不抛弃它们并重新开始，因为我们需要将我们的思维方式从我们原来的方法转移开来。更糟糕的是，我们以骄傲的态度参加了第一次会议，因为我们认为我们知道这一切，如果不是因为我们的销售人员的花哨操作，这种态度会让我们失去客户。最重要的是，我们在创建模型时并不需要模型，而是在与客户交谈并确保销售后，我们应该等待创建模型。

另一个例子是，RUP建议您创建一个软件体系结构描述（SAD）文档来定义您的体系结构。是的，定义您的系统架构是非常好的事情，正如我在敏捷架构中讨论的那样，但您是否需要在项目早期创建文档？有时是，有时没有。几年前，我在一个关键任务系统上工作，我们在一个普通的旧白板（POW）上开发了我们的架构模型，我们遵循公开展示模型，作为自由格式图的集合。因为这个过程告诉我们创建一个SAD，所以我们这样做了，尽管大多数开发人员都使用白板草图。因为RUP产品为SAD提供了相当不错的Microsoft Word模板，所以我们使用它作为工作的基础。一些开发人员从SAD文档打印出图表，我们已将我们的草图转录到Microsoft Visio中，以便粘贴到他们的隔间墙上，因为他们无法轻易地看到他们坐在哪里的图表。每次白板草图发生充分变化时，我们都必须更新图表的电子版本以及SAD文档中的相应部分。获得SAD文档的好处在于它提供了我们正在构建的内容的描述，这是我们分发给管理层的文档，并且可供组织内任何感兴趣的人使用。据我所知，缺点是没有人有效地使用SAD文件。我不确定经理们是否曾经看过它，如果他们这样做，那最多只是粗略的检查，因为我们从未收到任何来自他们的反馈。需要图表副本的开发人员可以轻松地拍摄草图的数字快照，或者创建共享的架构网页，或者只是打印出来。这也可能是一个SAD文档，尽管形式不同，根据原则内容比表示更重要，因为它仍然会描述我们的架构（这是SAD文档的基本目的）。同样的推理我们的白板草图也是一个SAD文档，虽然一个不是永久性的，一个固定在永久位置的。在我看来，我们犯了三个基本错误，因此比我们需要的更重：我们选择了错误的文档格式，我们过早记录，并且我们创建了太多的文档。将SAD作为Word文档维护的额外开销减缓了我们的速度，因为我们在多个位置实际拥有了这些信息 - 我们正在处理的白板，几乎是多余的Word文档，以及我们的代码本身。此外，我们本来可以开发软件而不是文档，更糟糕的是更新工作占用了我们的一位高级开发人员的大部分时间，所以他无法帮助指导和指导初级开发人员。当然，在项目结束时将此文档作为我们向维护团队提供的可交付成果之一是有用的，但我们在开发过程中肯定不需要它，这显然对项目团队造成了更大的伤害。

旅行灯需要你思考你在做什么。在项目开始时，根据项目的性质，问问自己您认为自己需要什么。与静态HTML页面制作的网站开发相比，开发空中交通管制系统可能需要更多的文档。随着项目的进展，您会发现您对文档的初始估计需要根据经验进行更改，或许您需要更多或更少。 Highsmith喜欢使用徒步旅行的类比，他是登山者 - 包装太轻或太重都会导致灾难，最糟糕的是它会杀死你，最多会迫使你回头重新思考你的策略。想象一下，穿越沙漠的水不足，你旅行太轻，或者试图穿过绑在背上的100磅重的沙漠，现在你旅行太重了。现在想象一下，构建一个关键任务电子商务应用程序而不提供任何描述如何操作它的文档，您的项目实际上会失败，因为您的行程太轻了。现在想象一下，构建包含数千页文档的相同系统，每次更改系统时都必须更新和验证，然后再次失败，因为您的行程非常繁重，无法快速响应市场变化。行车灯意味着足够的模型和文档，太少或太多会让您处于危险之中。

8.什么是文档敏捷？

无论有些人会告诉你什么，文档实际上可以非常有效。什么时候文件敏捷？满足以下条件时：

敏捷文档最大化利益相关者的ROI。敏捷文档提供的好处大于其创建和维护的投资，理想情况下，该文档中的投资是这些资源的最佳选择。换句话说，文档必须至少提供正值，并且理想情况下提供最佳价值。例如，如果创建用户文档提供50％的投资回报，但为用户提供培训课程可提供100％的回报，那么您最好选择培训，因为这是一项更好的投资。
利益相关者知道文件的总体拥有成本。利益相关者必须了解文档的总体拥有成本（TCO），并愿意投资于该文档的创建和维护。
敏捷文档“精益充沛”。敏捷文档包含足够的信息来实现其目的，换句话说，它尽可能简单。例如，敏捷文档的某些部分可以用点式而不是散文来编写 - 您仍然可以捕获关键信息而无需花费时间使其看起来漂亮，这符合内容比表示更重要的原则。敏捷文档通常会提供对其他信息源的引用，例如，描述外部系统接口的合同模型可能表明正在使用SOAP 1.1协议，并提供对定义XML文档的XML DTD和模式定义的引用在系统之间传输。编写敏捷文档时，请记住Assume Simplicity的原则，即最简单的文档就足够了，并尽可能遵循“创建简单内容”的做法。
敏捷文档实现了目的。敏捷文档具有凝聚力，它们实现了一个明确的目的。如果您不知道创建文档的原因，或者创建文档的目的是否有问题（参见前面的内容），那么您应该停下来重新考虑您正在做什么。
敏捷文档描述了“要知道的好事”。敏捷文档捕获关键信息，不易明显的信息，如设计原理，要求，使用程序或操作程序。敏捷文档不会捕获明显的信息。例如，指示CUSTOMER表的F_NAME列捕获客户名字的文档确实没有为我提供很多价值。指示客户表不包含居住在加拿大育空地区的客户的数据的文档，因为监管原因该数据存储在另一个系统上的ASCII平面文件中，这可能是很好的信息。
敏捷文档具有特定客户并促进该客户的工作。系统文档通常是为维护开发人员编写的，提供了系统体系结构的概述，并可能总结了关键需求和设计决策。用户文档通常包括使用用户理解的语言编写的系统的教程，而操作文档描述如何运行系统，并使用操作人员可以理解的语言编写。不同的客户，不同类型的文件，以及很可能不同的写作风格。如果您想要创建实际满足其需求的东西，您必须与客户或潜在客户密切合作以获取文档。例如，我会谨慎地为维护开发人员编写系统文档而不涉及其中的一些工作。是的，有时您无法让这些人参与进来（您目前可能没有工作人员），或者您可能无法确定维护组织中谁将成为您系统的最终“所有者”。当您没有涉及客户时，您将面临创建过多文档或不必要的文档的风险，从而变得不那么灵活。您经常会发现，当您让客户参与时，他们通常非常了解他们实际需要什么，并且经常可以提供适合他们和不适合的示例。
敏捷文档足够准确，一致且详细。您是否曾使用过描述该软件以前版本的书籍来学习如何使用新软件？你成功了吗？有可能。这是一个完美的情况吗？可能不是。它是否涵盖了该软件的所有新功能？当然不是，但它仍然让你运行软件包。您是否愿意花30美元购买最新版本的书？可能不是，因为它不值得你。敏捷文档不需要是完美的，它们只需要足够好。

但是，说了这些之后，您需要采取敏捷文档需要足够好的建议。如果您正在编写核电站软件系统的操作手册，那么我强烈建议您做对！但是，很少有系统真的那么重要，因此投入所需的努力来完善文档是不合适的。在编写文档时，您需要进行判断调用，关键问题是确定文档客户可以接受多少模糊性并且仍然可以有效地完成工作。

9.您应该创建哪些类型的文档？

您需要在项目中创建文档，即使是最“极端”的XP项目也是如此，更不用说RUP项目了。但是您可能需要创建哪些类型的文档？表1列出了您可能决定在开发工作中创建的一些最常见的文档，这些文档将作为整个系统的一部分提供。表1不包括管理工件，例如项目进度表，软件可交付成果（如源代码和测试套件）或临时工作产品（如临时模型）。

表1.开发团队要创建的潜在文档。

Potential Document	Audience	Description	Advice	Valuable Deliverable?
Contract models	Other Teams	A document describing the technical interface to a system or portion of a system.	See Introduction to Contract Models	Yes
Design decisions	Developers, Maintenance Developers, Project Managers	A summary of critical decisions pertaining to design and architecture that the team made throughout development	Question the need for most of this information. Are people really going to care several years from now why you did something? Focus on decisions that are not obvious, which had other reasonable alternatives, or ones where you explored what initially looked like a reasonable alternative that in the end proved insufficient for your needs. The goal of this effort is to avoid needless refactoring at some point in the future or rehashing a previously made decision. Design decisions are often documented throughout other artifacts, such as system overviews and source code, although you may choose to have a separate document when appropriate to the situation.	Perhaps
Executive Overview/Vision Statement	Senior Management, User Management, Project Management	A definition of the vision for the system and a summary of the current cost estimates, predicted benefits, risks, staffing estimates, and scheduled milestones. Advanced: Consider including listing of major stakeholder groups, their representatives (if any), and their primary goals.	This document is typically used to gain funding and support for your project as well as provide status updates to important project stakeholders who may not be actively involved with your project on a day-to-day basis. Keep it short, ideally a few pages, and consider writing it in point form. Have the courage to make this publicly available to everyone that should have access to it, even when it contains bad news, according to the principle Open and Honest Communication.	Valuable interim document
Operations documentation	Operations Staff	This documentation typically includes an indication of the dependencies that your system is involved with; the nature of its interaction with other systems, databases, and files; references to backup procedures; a list of contact points for your system and how to reach them; a summary of the availability/reliability requirements for your system; an indication of the expected load profile of your system; and troubleshooting guidelines.	Your operations department often has a standard format for this type of documentation or at least may have good examples from other systems that they can provide you to base your document(s) on.	Yes
Project overview	Developers, Managers, Maintenance Developers, Operations Staff	A summary of critical information such as the vision for the system, primary user contacts, technologies and tools used to build the system, and the critical operating processes (some applicable to development, such as how to build the system and some applicable to production, such as how to back up data storage). Also provides references to critical project artifacts such as the source code (the project name in the source code control system is often sufficient), where the permanent models pertaining to the system (if any) are, and where other documents (if any) are.	I typically create and maintain this document during development. Keep it short and to the point, I don't ever remember one getting beyond ten printed pages and most are less than five. This document serves as a starting point for anyone new to the team, including maintenance developers, because it answers fundamental questions that they are likely to have. Whenever you first share this document with anyone ask them to keep track of major issues that they were not able to easily resolve using this document, or any misinformation they discover, to provide insight into potential updates for the document. I often call this a "Good Things to Know" document.	Yes
Requirements document	Developers, Maintenance Developers,Users, User Managers	This document defines what the system does, summarizing or composed of requirements artifacts such as business rule definitions, use cases, user stories, or essential user interface prototypes (to name a few).	Writing a requirements specification early in the life cycle should be seen as a very large risk. XP projects typically favor inclusive requirements techniques such as user stories and CRC cards. RUP projects tend towards more formal requirements artifacts and documentation. Disciplined agile teams capture the majority of their requirements as executable specifications. As a result these teams only need brief overviews of the scope which would be part of the system documentation.	In scaling situations, particularly when regulatory compliance, large teams, or geographically distributed teams are an issue
Support documentation	Support Staff	This documentation includes training materials specific to support staff; all user documentation to use as reference when solving problems; a trouble-shooting guide; escalation procedures for handling difficult problems; and a list of contact points within the maintenance team.	You will find that your support department often has a standard escalation procedure in place, therefore you will not need to write one, and like the operations department may have standard templates or examples that you can work from.	Yes
System documentation	Maintenance Developers, Developers	The purpose of this document is to provide an overview of the system and to help people understand the system.Common information in this document includes an overview of the technical architecture, the business architecture, and the high-level requirements for the system. Detailed architecture and design models, or references to them, may also be included where appropriate.	System documentation helps to reduce perceived risk on the project by providing "truck insurance", the assurance that if the development team leaves, or gets hit by a truck[1], that critical information about the project is left behind. Unfortunately this is typically false insurance-if you lose someone(s) then no matter how good the documentation is you have a serious problem on your hands because new people still need to be identified, assigned to your system, and need to learn the system. You're much better off increasing your project's "truck number", the minimum number of people that if you lost them would put your project at risk, by supporting knowledge sharing practices such as Active Stakeholder Participation, Collective Ownership, and Model With Others.	Yes
User documentation	Users, User Managers	Your users may require a reference manual, a usage guide, a support guide, and even training materials. It's important that you distinguish between these different types of documents because the way that each one is used varies: one is for quick lookups, one is for discovering about how to work with the system, one is for how to obtain additional help, and one is for training.	.I typically base my usage guide and training materials on the use cases for the system -the use cases describe how the actors work with the system, therefore they should be a very good foundation on which to base both of these documents. .User documentation should be considered part of the user interface for your system and therefore should undergo usability testing.	Yes

观察：有时不敏捷能够实现敏捷。敏捷软件开发对许多组织来说都是新的，因此对其可行性存在极大的恐惧和不确定性，虽然有时令人沮丧但这实际上是一件好事，因为这意味着人们关心。由于这种担心，您的项目利益相关者可能会要求您创建无关的文档以帮助他们放心，特别是对于过去可能被其他新技术和技术焚烧的高级管理人员而言。通常，单个文档的创建（可能是执行概述）将为您的项目利益相关者提供足够的关于项目的“温暖和模糊的感觉”，以允许您以您选择的方式工作（例如以敏捷方式）。

10. Agilists是否真的创建文档并且它是否有用？

问题第一部分的答案肯定是肯定的。 DDJ的2008年建模和文档调查发现，敏捷团队与传统团队一样可以编写可交付文档，如用户手册，操作文档等。图4总结了与可交付文档有关的调查结果。重要的是，这项调查应该有助于浪费人们在敏捷软件开发和文档方面遇到的一些误解。

图4.可交付文档创建。

Chance that a team will create deliverable documentation

问题的第二部分的答案可能是。在DDJ 2009年9月的IT联盟状态中，我们探讨了开发团队按照各种范例生成的可交付文档的质量，其结果如图5所示。您可以看到敏捷团队生成的文档的报告质量与传统团队处于同一水平，尽管迭代团队似乎比两者都更有效。图5的有趣之处在于，在文档质量方面发现了所有开发范例（它们都具有负分数，因此直方图上的所有条形都朝左）。

图5.“可交付文档”的质量。

Quality of deliverable documentation

11.何时应创建文档？

让我们从一些基本建议开始（在本文的其他地方详细描述）：

优先于静态规范的可执行规范（文档）
单一来源信息
记录稳定的概念，而不是推测性概念，从而在生命周期中尽可能晚地记录
文档是最不有效的沟通方式

现在让我们考虑在软件开发生命周期（SDLC）中何时编写文档是有意义的。图6描绘了传统和敏捷开发文档的典型策略，曲线表示迄今为止在编写文档时投入的总工作量。在这种情况下，文档包括临时工作产品，例如项目计划和规范，您可能不会决定在项目结束时保留这些产品（一些团队会这样做，一些团队不会）。该图还指出了在给定时间点可能创建的文档类型，尽管此列表并不是详尽无遗的。图6实际上描述了文档后期最佳实践的策略。

图6.通过SDLC的文档 - 文档延迟策略。

Agile Documentation - Document Late strategy

另一种更有纪律的方法是随时记录支持，操作，系统概述和用户文档。图7中概述了该策略。该想法是，如果系统在每次迭代结束时可能是可交付的，那么也包括可交付文档。挑战在于，您编写的任何文档都需要随着时间的推移与您的代码同步发展，这可能很痛苦（请参阅下一节）。如果采用此策略，则需要考虑三种启发式方法：

对于四周或更长时间的长迭代，请在迭代中编写文档，以便开发相应的功能。
对于两周或更短的短迭代，考虑在下面的迭代中编写文档（尽管努力将其写为迭代）。
无论迭代长度如何，您都需要尝试两种方法来找出最适合您的方法。最后，这两种策略通常最终会有所不同，因为通过长时间的迭代，您将倾向于将文档编写到迭代的最后。

图7.通过SDLC的文档 - 文档连续策略。

Agile Documentation - Document Continuously strategy

随着文档的不断接近，许多团队将在其迭代完成定义中包含有关更新可交付文档的标准。

12.何时应更新文档？

在这方面文件就像模型一样，我的建议是遵循练习更新时只有它会受伤。像敏捷模型这样的敏捷文档就足够了。很多时候文档可能已经过时而且并不重要。例如，当我编写本文的第一个版本时，我正在使用早期版本的JDK v1.3.1但我经常使用参考手册JDK 1.2.x-这不是一个完美的情况，但我没有太多的悲伤，因为我使用的手册仍然足够好。Java v1.0.x的手册是否足够？可能没有，因为自那次发布以来发生了重大变化，我的生产力损失将远远大于新手册的成本。

除了项目利益相关者授权投入完成工作所需资源的基本要求之外，您还应该使用以下启发式方法来决定何时更新文档：

更新合同模型并在发布模型描述的项目之前进行理想的重新发布，并且最低限度地并行发布。
作为系统一部分的文档（例如操作和用户手册）应在系统本身之前或与系统本身一起更新和发布。
文档的客户受到了极大的伤害，包括显着的生产力损失，因为文档没有更新（例如，它会受到伤害）。

是的，如果模型和文档不完全准确或彼此不完全一致，则会令人沮丧。这种挫败感被行驶灯固有的生产率提高所抵消，不需要不断地使文档和模型保持最新并且彼此一致。你想写软件还是写文档？

13.有效的文档切换

当一个团体或个人向另一个团体或个人提供文档时，会发生文档切换。敏捷开发人员拼命试图避免文档切换，因为它们不是人们沟通的好方法。遗憾的是，在某些情况下，文档切换是现实的 - 您的开发团队是如此之大，以至于无法共存，可能是另一家公司正在创建子系统（意味着需要合同模型），也许重要的项目利益相关者是您的团队无法随时使用，或许您所在行业或组织的法规要求生成某些文档，或者您的团队可能由专家组成，而不是概括专家。以下策略有助于提高文档切换的有效性：

避免文档切换。当您迁移到敏捷软件开发过程时，您将不断遇到那些不那么灵活的人，他们认为文档切换没有任何问题。指出有更好的沟通方式 - 面对面对话，视频会议，电话会议 - 在编写文档之前应该考虑，并尽可能尝试找到满足您需求的更好方法。
支持与其他通信方式的切换。如果您无法避免向其他人提供文档，您至少应该努力通过面对面交流或其他方法来支持切换。这可以使您编写更少的文档，从而使您可以专注于其他活动，并将帮助您避免文档的一些常见缺点，例如误解材料。
避免文档切换。你正在与之交往的人不喜欢写作和接收文档的机会很好 - 至少它不会有问题。
编写敏捷文档。请参阅“提高文档敏捷性的策略”一节。
避免文档切换。我不能强调这一点。

14.模板可以帮助吗？

是的，不是。我的经验是，专注于捕获文档中所需的最小，关键信息的简单模板非常有用。遗憾的是，许多模板与此完全相反，并尝试捕获您在任何情况下可能需要的所有信息。由于以下几个原因，这些模板被证明是无效的：

该模板耗时且创建成本高。创建综合模板需要付出巨大努力。
人们实际上会把它们填满。综合模板将包含不适用于给定项目的字段。有些人会看到该字段并试图填写它，浪费他们的时间并降低文档的价值，因为它现在包含不必要的信息，可能会在以后混淆用户。其他人会选择表明该字段不是必需的，这也需要时间。
评论需要更长时间现在有更多的信息需要审查，有些信息可能是上面提到的不必要的信息。审查通常会在遇到表明不需要的字段时放慢速度，因为人们经常会质疑该决定。
总体拥有成本（TCO）增加。您编写的文档越多，您旅行的文件就越重，减慢速度并提高文档的总体TCO。

15.如何减少文件损失？

“Cruft”是一个俚语，指的是设计糟糕，实施不当或多余的东西。重要的是要注意，cruft部分基于这样的感觉：除了该工件的实际质量之外，某人还具有工件。关于文档，当包含过时，冗余，范围外或写得不好的信息时，就会发生错误。表2概述了减少文档中的瑕疵的策略。该文件的CRUFT评级，100％是一件坏事，使用以下公式计算：100％ - C * R * U * F * T，其中以下因素以百分比衡量：

C =当前“正确”的文档的百分比。
R =目标受众阅读文档的可能性。
U =目标受众实际理解的文档百分比。
F =将遵循文档中包含的材料的可能性。
T =文档可信任的可能性。

表2：减少文件损失的策略。

Factor	Improvement Strategy
C = How correct is the document?	Minimize the information contained in the document Single source information by capturing it in one place only Have more than one person work on the document together (i.e. pair write the document and thereby do inspections in progress) Have shared ownership of all documentation so that multiple people will work on it Document stable, not speculative concepts
R = Will the document be read?	Work closely with the audience of the document so that you know what they actually require of it
U = Will the document be understood?	Take an evolutionary (iterative and incremental) approach to its development so that you gain feedback as to its actual value
F = Will the document be followed?	Prefer executable specifications, such as customer tests and developer tests, over static specifications such as traditional requirements and design documents. By doing so the specification actually provides value to the audience Capture high-level information in documentation, not details. When you specify details of how to do something and then hand the document to someone for them to follow, you effectively take all of the joy out of the activity for that person because you've done the thinking for them. What would the motivation be for an intellectual worker, such as an IT professional, to follow detailed instructions?
T = Will the document be trusted?	Work closely with the audience of the document Take an evolutionary approach

16.文档什么时候是最佳选择？

很少。让我们考虑一下您考虑编写文档时的情况：

在开发过程中传达信息。传统的软件开发理论要求在整个软件开发生命周期中创建详细的文档。虽然这在理论上听起来是一个很好的策略，但在实践中它证明会增加您的总体成本和项目风险。原因是文档实际上是一种非常糟糕的通信方式，如图8所示。这个图表的含义是，您应该根据当前情况选择最适合您的通信选项。文档选项，特别是“纸张规格”是您最不希望的选择，而不是最理想的选择。
指定一些东西。敏捷专家已经证明，通过采用测试驱动开发（TDD）方法，您可以在即时（JIT）基础上有效地创建详细的可执行规范。为了扩展TDD，我们采用敏捷模型驱动开发（AMDD）方法来解决以测试形式无法轻易捕获的高级问题。因此，一些高级规范可能有助于支持您的其他通信工作。
永久记录信息。这是文档开始有意义的地方。您仍然希望以最佳方式为您的受众捕获信息，例如，维护程序员显然更喜欢高质量的源代码，完整的测试套件以及高度详细的系统文档的一些概述文档。您仍然需要编写支持文档，操作文档和用户文档，但传统团队编写的许多技术文档在实践中似乎很少有效。
符合规定。无论喜欢与否，我们都生活在监管世界中。萨班斯 - 奥克斯利法案和食品药品管理局（FDA）指南等行业法规通常会激励人们编写比平常更多的文档，这通常是件好事。然而，在阅读了这些监管指南中的一些之后，我还没有看到一个人说要写一堆无用的文件，或者说你的钱非常浪费。然而，在实践中，许多组织选择这样做。我的建议是阅读法规，然后找到满足要求的有效方法。如果你让我们当中的官僚解释这些规定，那么当你最终采用官僚主义的方法时，不要感到惊讶。

图8.比较各种通信模式的有效性。

Comparing communication modes