宁愿编写代码?还是把事情都写下来吧!

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

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

那文档就一无是处吗?我想你知道答案。
为什么要写下来

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

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

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

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

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

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

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

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

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

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

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

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

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

写文档需要成为习惯

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

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

查看英文原文:I’d Rather Be Coding – Writing Things Down

This entry was posted in Best Practices. Bookmark the permalink.

发表评论

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / 更改 )

Twitter picture

You are commenting using your Twitter account. Log Out / 更改 )

Facebook photo

You are commenting using your Facebook account. Log Out / 更改 )

Google+ photo

You are commenting using your Google+ account. Log Out / 更改 )

Connecting to %s