寧願編寫程式碼？還是把事情都寫下來吧！

　　開發者真的非常討厭花時間寫東西，除非寫的是程式碼。然而他們還對這種厭惡振振有詞：

• 如果不是程式碼，它就無法通過編譯，也無法確定它是不是有意義。
• 如果不是程式碼，它就無法執行，所以可能永遠無法用於完成任何事情。
• 如果不是程式碼，也就無法對它進行測試，因此也無法證明它的真實與正確。
• 敏捷宣言中甚至都不再強調文件：可以工作的軟體勝過面面俱到的文件。

　　那文件就一無是處嗎？我想你知道答案。

　為什麼要寫下來

　　很多時候，專案中的些許文件會起到很大的作用。但是要得到那些好處，開發者必須停下手中的程式碼，抽點時間把事情寫下來。我來舉一些例子，我想他們會發現文件物有所值。

　記下因何而做的決定

　　如果專案不止持續幾個月，總有這樣的時候，所做的決定會改變開發過程。可能是決定使用（或明確地避免使用）某個特定的工具、框架或平臺；可能是決定以某種方式編寫測試，或是在某些情況下根本不編寫測試；可能是決定丟掉慣常的實踐方式，並且以完全不同的方式做事。這些決定將會出現，而且往往會持續下去。

　　在做下決定很久之後的某一天，團隊裡的某個人（通常是新加進來的，他們很煩人，是不是？）會問“我們為什麼這麼做？”。他們會得到什麼樣的答案呢？

　　如果團隊裡有一個人或幾個人記性不錯，而且這個專案他們也跟得足夠久了，新的團隊成員或許能得知真實原因。但是大部分情況下，恐怕答案是“因為我們總是這麼做的”。誰都不想聽到這樣的答案。

　　請記住，如果碰到這樣的答案，可以有所選擇。你可以按照往常做事的方式繼續做下去，因為你已麻木，或是因為這樣做更為安全，你已經不記得開始這樣做的原因了。作為選擇，你可以作出改變，希望你考慮了所有可能的影響。究竟會出什麼問題呢？哦，後來發現問題多的是。例如：

• 你可能走了一條已經被探索過而且被否定了的路，浪費寶貴的專案時間和精力。
• 你的修改可能與客戶要求的系統工作方式相沖突，讓客戶非常懊惱。
• 本來有所緩和的合規審查可能因為你的做事方式而破壞，並使你和/或你的客戶遇到法律上的麻煩。

　　只需要花點時間把事情寫下來，這些後果都可以避免。當你的團隊做了會改變你工作方式的決定時，把當時的日期以及決策背後的邏輯考慮寫下來。以後，當有人問起“為什麼那樣做”或“為什麼使用那個工具”時，你就可以自信滿滿地回答了。

　為將惱人的過程自動化做好準備

　　開發者經常會發現他們想將一些過程自動化。這些過程經常重複，而且會浪費寶貴的開發時間。然而，我時常碰到一些執行不那麼頻繁的手工過程（可能幾個月一次），這些過程會涉及一系列步驟，必須按照特定的順序完成。如果沒人願意費點力氣把這個過程寫下來，那就有很大的機會出現執行錯誤的情況，或者是執行中漏掉了某些步驟，浪費的時間甚至更多。此外，如果不先把這些步驟寫下來，我們也就沒有切實可行的方式將這個過程自動化。

　　如果你發現自己正在執行的任務有多個步驟，而且這個任務有很大的機會要再次執行，請把這些步驟寫下來。當再有人必須手工執行該過程時，能夠節省時間，可能有一天你終於感到非常氣餒，於是你將這個過程自動化了，而今天的行動也為那一天做好了準備。

　作為後手

　　在敏捷專案中，正如敏捷宣言所述，我們更重視面對面的交流。這樣交流需求是最好的，因為不管是口頭資訊，還是非口頭資訊，都可以收集到。然而，交流的話可能被誤解，更有可能被記錯。任何一方都可能出現這種問題：開發者可能認為他們聽到了，但是客戶並沒有說過，或者客戶忘了（假定他們都是無意為之）他們曾讓開發者選擇某一特定方向。 這就致使開發者最後只是堅稱某些行動是客戶讓他們做的，但到底是不是這樣，卻沒有任何證據。在這種情況下，我的經驗是，獲勝的幾乎總是客戶，而開發者只能帶著失意或者可能是被侮辱了的感覺走開。

　　看上去開發者並不希望發生這樣的事。我們來看看，這種情況應該如何避免呢？我不知道……或許我們可以嘗試一下把東西寫下來？我們需要做的就是在電話或面對面的會議之後寫封郵件，用開發者的話描述一下，在他們看來，客戶讓他們做哪些事。這不需要多大力氣，而且當“系統為什麼要那樣開發”之類的問題出現時，真是很好的跟蹤證據。

　使編寫文件容易進行的一些想法

　　對大部分人來說，文件並不是自然而然的；而對大部分開發者來說，文件則完全是一種痛苦。然而，上面已經解釋過，文件有其價值。下面是一些讓寫文件不那麼痛苦的想法：

• 立即寫下來。當碰到不喜歡做的事情時，我們中有很多人喜歡拖延。對於這類文件，可別這麼做。最好是趁熱打鐵，在你不需要停下來回憶的時候寫下來更容易。一談完，就找個工作站或用移動裝置把摘要寫下來。
• 藉助好工具。說到移動裝置，有很多極好的工具，可以用來記事。早先，即便是最簡單的東西，我們也必須在wiki上找到一個合適的地方，並使用某些不那麼直觀的標記語言將它寫下來。現在，我們有了無所不在的Evernote和OneNote，還有很多類似的工具；還有部落格和微博（在你的專案中，使用Twitter是不可能的嗎）；如果其他所有的工具都不行，還有電子郵件呢。找出你最喜歡的即可。
• 保持簡短。每次討論的文件不需要很長。即使不能使用Twitter，也可以假裝在使用——讓資訊簡明扼要、切中要害。在140個字內你能說些什麼，使得描述的內容足夠有用，同時又能讓人快速抓住要點？文件被不止一次閱讀的可能性與其長度成反比。
• 把它記到你能再次找到的地方。如果需要的時候找不到，那記下來也沒什麼用。把它記在看上去最明顯的位置（比如，放在建立好的專案文件倉庫中，和程式碼放到一個地方，或者放到發給所有團隊成員的電子郵件中），能以電子方式搜尋的地方比較理想。不要只是將其記在團隊辦公區的白板上（儘管除了將其記在可以長期儲存的地方，你還想使用白板）。你可能想把資訊記在多個地方，看看在哪裡能找到……你甚至可以就內容能夠被找到的地方收集一些指標，以此來決定最好的儲存位置。我知道，對某些人而言，這可能有點瘋狂。

　寫文件需要成為習慣

　　正如我上面所說，將專案中日常出現的小事寫成文件並不是自然而言就會去做的。你必須強迫自己這麼做。我知道你寧願編寫程式碼，但是一定要讓自己這麼做；我保證物有所值。如果一有事發生，你就能讓自己跳到記事系統，這很快就會成為老習慣了。那時你就會驚訝，以前不記文件是怎麼過來的啊。

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