宁愿编写代码？还是把事情都写下来吧！

        英文原文：I’d Rather Be Coding – Writing Things Down

        开发者真的非常讨厌花时间写东西，除非写的是代码。然而他们还对这种厌恶振振有词：

• 如果不是代码，它就无法通过编译，也无法确定它是不是有意义。
• 如果不是代码，它就无法执行，所以可能永远无法用于完成任何事情。
• 如果不是代码，也就无法对它进行测试，因此也无法证明它的真实与正确。
• 敏捷宣言中甚至都不再强调文档：可以工作的软件胜过面面俱到的文档。

        那文档就一无是处吗？我想你知道答案。

        为什么要写下来

        很多时候，项目中的些许文档会起到很大的作用。但是要得到那些好处，开发者必须停下手中的代码，抽点时间把事情写下来。我来举一些例子，我想他们会发现文档物有所值。

        记下因何而做的决定

        如果项目不止持续几个月，总有这样的时候，所做的决定会改变开发过程。可能是决定使用（或明确地避免使用）某个特定的工具、框架或平台；可能是 决定以某种方式编写测试，或是在某些情况下根本不编写测试；可能是决定丢掉惯常的实践方式，并且以完全不同的方式做事。这些决定将会出现，而且往往会持续 下去。

        在做下决定很久之后的某一天，团队里的某个人（通常是新加进来的，他们很烦人，是不是？）会问“我们为什么这么做？”。他们会得到什么样的答案呢？

        如果团队里有一个人或几个人记性不错，而且这个项目他们也跟得足够久了，新的团队成员或许能得知真实原因。但是大部分情况下，恐怕答案是“因为我们总是这么做的”。谁都不想听到这样的答案。

        请记住，如果碰到这样的答案，可以有所选择。你可以按照往常做事的方式继续做下去，因为你已麻木，或是因为这样做更为安全，你已经不记得开始这样做的原因了。作为选择，你可以作出改变，希望你考虑了所有可能的影响。究竟会出什么问题呢？哦，后来发现问题多的是。例如：

• 你可能走了一条已经被探索过而且被否定了的路，浪费宝贵的项目时间和精力。
• 你的修改可能与客户要求的系统工作方式相冲突，让客户非常懊恼。
• 本来有所缓和的合规审查可能因为你的做事方式而破坏，并使你和/或你的客户遇到法律上的麻烦。

        只需要花点时间把事情写下来，这些后果都可以避免。当你的团队做了会改变你工作方式的决定时，把当时的日期以及决策背后的逻辑考虑写下来。以后，当有人问起“为什么那样做”或“为什么使用那个工具”时，你就可以自信满满地回答了。

        为将恼人的过程自动化做好准备

        开发者经常会发现他们想将一些过程自动化。这些过程经常重复，而且会浪费宝贵的开发时间。然而，我时常碰到一些执行不那么频繁的手工过程（可能 几个月一次），这些过程会涉及一系列步骤，必须按照特定的顺序完成。如果没人愿意费点力气把这个过程写下来，那就有很大的机会出现执行错误的情况，或者是 执行中漏掉了某些步骤，浪费的时间甚至更多。此外，如果不先把这些步骤写下来，我们也就没有切实可行的方式将这个过程自动化。

        如果你发现自己正在执行的任务有多个步骤，而且这个任务有很大的机会要再次执行，请把这些步骤写下来。当再有人必须手工执行该过程时，能够节省时间，可能有一天你终于感到非常气馁，于是你将这个过程自动化了，而今天的行动也为那一天做好了准备。

        作为后手

        在敏捷项目中，正如敏捷宣言所述，我们更重视面对面的交流。这样交流需求是最好的，因为不管是口头信息，还是非口头信息，都可以收集到。然而， 交流的话可能被误解，更有可能被记错。任何一方都可能出现这种问题：开发者可能认为他们听到了，但是客户并没有说过，或者客户忘了（假定他们都是无意为 之）他们曾让开发者选择某一特定方向。 这就致使开发者最后只是坚称某些行动是客户让他们做的，但到底是不是这样，却没有任何证据。在这种情况下，我的经验是，获胜的几乎总是客户，而开发者只能 带着失意或者可能是被侮辱了的感觉走开。

        看上去开发者并不希望发生这样的事。我们来看看，这种情况应该如何避免呢？我不知道……或许我们可以尝试一下把东西写下来？我们需要做的就是在 电话或面对面的会议之后写封邮件，用开发者的话描述一下，在他们看来，客户让他们做哪些事。这不需要多大力气，而且当“系统为什么要那样开发”之类的问题 出现时，真是很好的跟踪证据。

        使编写文档容易进行的一些想法

        对大部分人来说，文档并不是自然而然的；而对大部分开发者来说，文档则完全是一种痛苦。然而，上面已经解释过，文档有其价值。下面是一些让写文档不那么痛苦的想法：

• 立即写下来。当碰到不喜欢做的事情时，我们中有很多人喜欢拖延。对于这类文档，可别这么做。最好是趁热打铁，在你不需要停下来回忆的时候写下来更容易。一谈完，就找个工作站或用移动设备把摘要写下来。
• 借助好工具。说到移动设备，有很多极好的工具，可以用来记事。早先，即便是最简单的东西，我们也必须在 wiki 上找到一个合适的地方，并使用某些不那么直观的标记语言将它写下来。现在，我们有了无所不在的 Evernote 和 OneNote，还有很多类似的工具；还有博客和微博（在你的项目中，使用 推ter 是不可能的吗）；如果其他所有的工具都不行，还有电子邮件呢。找出你最喜欢的即可。
• 保持简短。每次讨论的文档不需要很长。即使不能使用 推ter，也可以假装在使用——让信息简明扼要、切中要害。在 140 个字内你能说些什么，使得描述的内容足够有用，同时又能让人快速抓住要点？文档被不止一次阅读的可能性与其长度成反比。
• 把它记到你能再次找到的地方。如果需要的时候找不到，那记下来也没什么用。把它记在看上去最明显的位置（比 如，放在建立好的项目文档仓库中，和代码放到一个地方，或者放到发给所有团队成员的电子邮件中），能以电子方式搜索的地方比较理想。不要只是将其记在团队 办公区的白板上（尽管除了将其记在可以长期保存的地方，你还想使用白板）。你可能想把信息记在多个地方，看看在哪里能找到……你甚至可以就内容能够被找到 的地方收集一些指标，以此来决定最好的保存位置。我知道，对某些人而言，这可能有点疯狂。

        写文档需要成为习惯

        正如我上面所说，将项目中日常出现的小事写成文档并不是自然而言就会去做的。你必须强迫自己这么做。我知道你宁愿编写代码，但是一定要让自己这 么做；我保证物有所值。如果一有事发生，你就能让自己跳到记事系统，这很快就会成为老习惯了。那时你就会惊讶，以前不记文档是怎么过来的啊。

        关于作者

        Nate McKie 是 Asynchrony 的联合创始人与 CTO。Asynchrony 是一家位于密苏里州圣路易斯市的 IT 咨询公司。 Nate 带头，使 Asynchrony 成为了敏捷技术和理念的顶级实践者。通过该公司的商业和政府客户群，他也带头传播了高质量代码和快速实现的原则。Nate 的角色是推动公司的技术方面，并将敏捷技术传授给客户。你可以在 推ter 上关注 Asynchrony（@asynchrony）和 Nate McKie（@natemckie）。