寧愿編寫代碼？還是把事情都寫下來吧！
英文原文：I’d Rather Be Coding – Writing Things Down
開發者真的非常討厭花時間寫東西，除非寫的是代碼。然而他們還對這種厭惡振振有詞：
- 如果不是代碼，它就無法通過編譯，也無法確定它是不是有意義。
- 如果不是代碼，它就無法執行，所以可能永遠無法用于完成任何事情。
- 如果不是代碼，也就無法對它進行測試，因此也無法證明它的真實與正確。
- 敏捷宣言中甚至都不再強調文檔：可以工作的軟件勝過面面俱到的文檔。 </ul>
- 你可能走了一條已經被探索過而且被否定了的路，浪費寶貴的項目時間和精力。
- 你的修改可能與客戶要求的系統工作方式相沖突，讓客戶非常懊惱。
- 本來有所緩和的合規審查可能因為你的做事方式而破壞，并使你和/或你的客戶遇到法律上的麻煩。 </ul>
- 立即寫下來。當碰到不喜歡做的事情時，我們中有很多人喜歡拖延。對于這類文檔，可別這么做。最好是趁熱打鐵，在你不需要停下來回憶的時候寫下來更容易。一談完，就找個工作站或用移動設備把摘要寫下來。
- 借助好工具。說到移動設備，有很多極好的工具，可以用來記事。早先，即便是最簡單的東西，我們也必須在 wiki 上找到一個合適的地方，并使用某些不那么直觀的標記語言將它寫下來。現在，我們有了無所不在的 Evernote 和 OneNote，還有很多類似的工具；還有博客和微博（在你的項目中，使用 推ter 是不可能的嗎）；如果其他所有的工具都不行，還有電子郵件呢。找出你最喜歡的即可。
- 保持簡短。每次討論的文檔不需要很長。即使不能使用 推ter，也可以假裝在使用——讓信息簡明扼要、切中要害。在 140 個字內你能說些什么，使得描述的內容足夠有用，同時又能讓人快速抓住要點？文檔被不止一次閱讀的可能性與其長度成反比。
- 把它記到你能再次找到的地方。如果需要的時候找不到，那記下來也沒什么用。把它記在看上去最明顯的位置（比 如，放在建立好的項目文檔倉庫中，和代碼放到一個地方，或者放到發給所有團隊成員的電子郵件中），能以電子方式搜索的地方比較理想。不要只是將其記在團隊 辦公區的白板上（盡管除了將其記在可以長期保存的地方，你還想使用白板）。你可能想把信息記在多個地方，看看在哪里能找到……你甚至可以就內容能夠被找到 的地方收集一些指標，以此來決定最好的保存位置。我知道，對某些人而言，這可能有點瘋狂。 </ul>
那文檔就一無是處嗎？我想你知道答案。
為什么要寫下來
很多時候，項目中的些許文檔會起到很大的作用。但是要得到那些好處，開發者必須停下手中的代碼，抽點時間把事情寫下來。我來舉一些例子，我想他們會發現文檔物有所值。
記下因何而做的決定
如果項目不止持續幾個月，總有這樣的時候，所做的決定會改變開發過程。可能是決定使用（或明確地避免使用）某個特定的工具、框架或平臺；可能是 決定以某種方式編寫測試，或是在某些情況下根本不編寫測試；可能是決定丟掉慣常的實踐方式，并且以完全不同的方式做事。這些決定將會出現，而且往往會持續 下去。
在做下決定很久之后的某一天，團隊里的某個人（通常是新加進來的，他們很煩人，是不是？）會問“我們為什么這么做？”。他們會得到什么樣的答案呢？
如果團隊里有一個人或幾個人記性不錯，而且這個項目他們也跟得足夠久了，新的團隊成員或許能得知真實原因。但是大部分情況下，恐怕答案是“因為我們總是這么做的”。誰都不想聽到這樣的答案。
請記住，如果碰到這樣的答案，可以有所選擇。你可以按照往常做事的方式繼續做下去，因為你已麻木，或是因為這樣做更為安全，你已經不記得開始這樣做的原因了。作為選擇，你可以作出改變，希望你考慮了所有可能的影響。究竟會出什么問題呢？哦，后來發現問題多的是。例如：
只需要花點時間把事情寫下來，這些后果都可以避免。當你的團隊做了會改變你工作方式的決定時，把當時的日期以及決策背后的邏輯考慮寫下來。以后，當有人問起“為什么那樣做”或“為什么使用那個工具”時，你就可以自信滿滿地回答了。
為將惱人的過程自動化做好準備
開發者經常會發現他們想將一些過程自動化。這些過程經常重復，而且會浪費寶貴的開發時間。然而，我時常碰到一些執行不那么頻繁的手工過程（可能 幾個月一次），這些過程會涉及一系列步驟，必須按照特定的順序完成。如果沒人愿意費點力氣把這個過程寫下來，那就有很大的機會出現執行錯誤的情況，或者是 執行中漏掉了某些步驟，浪費的時間甚至更多。此外，如果不先把這些步驟寫下來，我們也就沒有切實可行的方式將這個過程自動化。
如果你發現自己正在執行的任務有多個步驟，而且這個任務有很大的機會要再次執行，請把這些步驟寫下來。當再有人必須手工執行該過程時，能夠節省時間，可能有一天你終于感到非常氣餒，于是你將這個過程自動化了，而今天的行動也為那一天做好了準備。
作為后手
在敏捷項目中，正如敏捷宣言所述，我們更重視面對面的交流。這樣交流需求是最好的，因為不管是口頭信息，還是非口頭信息，都可以收集到。然而， 交流的話可能被誤解，更有可能被記錯。任何一方都可能出現這種問題：開發者可能認為他們聽到了，但是客戶并沒有說過，或者客戶忘了（假定他們都是無意為 之）他們曾讓開發者選擇某一特定方向。 這就致使開發者最后只是堅稱某些行動是客戶讓他們做的，但到底是不是這樣，卻沒有任何證據。在這種情況下，我的經驗是，獲勝的幾乎總是客戶，而開發者只能 帶著失意或者可能是被侮辱了的感覺走開。
看上去開發者并不希望發生這樣的事。我們來看看，這種情況應該如何避免呢？我不知道……或許我們可以嘗試一下把東西寫下來？我們需要做的就是在 電話或面對面的會議之后寫封郵件，用開發者的話描述一下，在他們看來，客戶讓他們做哪些事。這不需要多大力氣，而且當“系統為什么要那樣開發”之類的問題 出現時，真是很好的跟蹤證據。
使編寫文檔容易進行的一些想法
對大部分人來說，文檔并不是自然而然的；而對大部分開發者來說，文檔則完全是一種痛苦。然而，上面已經解釋過，文檔有其價值。下面是一些讓寫文檔不那么痛苦的想法：
寫文檔需要成為習慣
正如我上面所說，將項目中日常出現的小事寫成文檔并不是自然而言就會去做的。你必須強迫自己這么做。我知道你寧愿編寫代碼，但是一定要讓自己這 么做；我保證物有所值。如果一有事發生，你就能讓自己跳到記事系統，這很快就會成為老習慣了。那時你就會驚訝，以前不記文檔是怎么過來的啊。
關于作者
Nate McKie 是 Asynchrony 的聯合創始人與 CTO。Asynchrony 是一家位于密蘇里州圣路易斯市的 IT 咨詢公司。 Nate 帶頭，使 Asynchrony 成為了敏捷技術和理念的頂級實踐者。通過該公司的商業和政府客戶群，他也帶頭傳播了高質量代碼和快速實現的原則。Nate 的角色是推動公司的技術方面，并將敏捷技術傳授給客戶。你可以在 推ter 上關注 Asynchrony（@asynchrony）和 Nate McKie（@natemckie）。