你是选择先写代码还是先把要做的事情记录下来？

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

　　如果不是代码，它就无法通过编译，也无法确定它是不是有意义。

　　如果不是代码，它就无法执行，所以可能永远无法用于完成任何事情。

　　如果不是代码，也就无法对它进行测试，因此也无法证明它的真实与正确。

　　敏捷宣言中甚至都不再强调文档：可以工作的软件胜过面面俱到的文档。

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

　　为什么要写下来

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

　　记下因何而做的决定

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

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

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

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

　　你可能走了一条已经被探索过而且被否定了的路，浪费宝贵的项目时间和精力。

　　你的修改可能与客户要求的系统工作方式相冲突，让客户非常懊恼。

　　本来有所缓和的合规审查可能因为你的做事方式而破坏，并使你和/或你的客户遇到法律上的麻烦。

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

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

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

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

　　作为后手

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

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

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

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

　　立即写下来。当碰到不喜欢做的事情时，我们中有很多人喜欢拖延。对于这类文档，可别这么做。最好是趁热打铁，在你不需要停下来回忆的时候写下来更容易。一谈完，就找个工作站或用移动设备把摘要写下来。

　　借助好工具。说到移动设备，有很多极好的工具，可以用来记事。早先，即便是最简单的东西，我们也必须在wiki上找到一个合适的地方，并使用某些不那么直观的标记语言将它写下来。现在，我们有了无所不在的Evernote和OneNote，还有很多类似的工具;还有博客和微博(在你的项目中，使用Twitter是不可能的吗);如果其他所有的工具都不行，还有电子邮件呢。找出你最喜欢的即可。

　　保持简短。每次讨论的文档不需要很长。即使不能使用Twitter，也可以假装在使用——让信息简明扼要、切中要害。在140个字内你能说些什么，使得描述的内容足够有用，同时又能让人快速抓住要点?文档被不止一次阅读的可能性与其长度成反比。

　　把它记到你能再次找到的地方。如果需要的时候找不到，那记下来也没什么用。把它记在看上去最明显的位置(比如，放在建立好的项目文档仓库中，和代码放到一个地方，或者放到发给所有团队成员的电子邮件中)，能以电子方式搜索的地方比较理想。不要只是将其记在团队办公区的白板上(尽管除了将其记在可以长期保存的地方，你还想使用白板)。你可能想把信息记在多个地方，看看在哪里能找到……你甚至可以就内容能够被找到的地方收集一些指标，以此来决定最好的保存位置。我知道，对某些人而言，这可能有点疯狂。

原文转自：http://www.admin10000.com/document/3786.html