> 原文出處：http://www.infoq.com/cn/articles/practices-lean-documentation 我在業余時間的一項調研讓我洞察到對高效率和高質量最重要的三件事就是知識、知識還是知識。最好的知識獲取途徑就是通過對話，與了解這方面知識的人的對話。不幸的是，很多情況下這樣的人并不在身邊。 當文檔是唯一的知識傳承手段時，本文將嘗試幫助讀者編寫有效而實用的文檔。本文中所展示的實踐都是基于我在一家大型跨國公司的項目中的工作經驗。 這一切源于一個開發人員對我說他有一個改善項目文檔的想法。我們就集合了一組對改善文檔感興趣的人并就一些規則達成了一致。 [TOC] ## 好文檔的規則 好的文檔應該： * 能夠快速方便地創建和更新。過時的信息比沒有信息更可怕。 * 能夠方便地提供正確答案。如果不能很方便地找到答案，就不會有人愿意使用。 * 不要代替人的交互。單獨的個體和通過流程和工具的交互，這樣對嗎？ 為了達成能夠滿足上述規則的目標，我們制定了六個實踐： ### 實踐一——識別閱讀文檔的用戶以及他們使用文檔的原因 盡管這聽起來顯而易見，但是很少有人真正這么做。在我們的項目中，我們的改進團隊識別了四個目標群組。 * 需要我們的工作內容的簡短總結的經理 * 需要快速介紹的新加入的開發人員 * 經過幾年其它項目之后重返當前項目的原系統開發人員 * 幫助客戶解決問題的故障排除人員  當我們問起他們對文檔的需求是，第一個目標群組用戶相當驚喜。首先，之前從未有人問過他們。哇！其次，他們甚至從未使用過他們所擁有的大量文檔。這一目標群組只需要三件事情的答案。總的來說，他們所需要的就是三行文檔。其他的文檔對于讀者和編者都是浪費時間。我的天！ ### 實踐二——像Google Earth那樣組織文檔 用戶使用文檔是為了找到他們的問題的答案。可以通過找到正確答案所需要的時間來衡量文檔的質量。我們用Google Earth作為模型。 你是否曾試圖在Google Earth上找到你的房子（通過下鉆而不是搜索地址的方式）？它花費了你多長時間？大概30到60秒？在地球表面找到你的房子就像在1.5萬億（1.5*1012）個答案中找到其中一個答案一樣。即使系統十分復雜龐大，找到答案的時間也不應該超過60秒。 如何將這一模型應用到文檔上呢？我們遵循了類似于Google Earth移動層級的層次結構：月亮級、衛星級、航拍級和直升機級等。每一層級都有一個簡短的介紹，我們稱之為電梯間演講，而且延續到下一層最多只有九種可能。  記住，并非所有的文檔工具都適于下鉆的方法。包含目錄結構的Word文檔可能就不是一個很好的主意。有指向下層鏈接的wiki就好很多。 ### 實踐三——保持小規模 我們討論了文檔化的原因并得出如下最小化文檔規模的原則： * 文檔應該是沒有時間和位置限制的溝通方式。不應該是實時溝通的替代品。 * 我們應該只留存結果而非需求。也就是說只有在推出新功能時，我們才更新或替換文檔而不是在拿到需求時就新增文檔。這樣就能確保文檔能夠準確地反映當前的系統狀態。 * 文檔所帶來的收益必須要大于創建和維護它的成本。不要將時間浪費在文檔化那些已經寫成代碼的知識上。文檔應該提供一個全局概覽和足夠的能夠幫助讀者快速找到必要代碼的信息。 適量的文檔就是在太短以致不實用和過長以致影響閱讀之間找到平衡。如果你不使用它，也就不會去更新它，而如果文檔過于陳舊并會產生誤導，也就變的毫無價值甚至會造成損失。 這是我從Henrik Kniberg那里得來的一些忠告： * 文檔數量越少越好—但不能更少 * 文檔長度越短越好—但不能更短 就這么簡單：） ### 實踐四——讓文字讀起來更吸引人 冗長、不切題的文檔讀起來讓人厭煩。如何才能讓文檔更切題？ 我們嘗試過這種辦法：我們請潛在的使用者與具有該知識的人進行面談。讀者比專家更知道他們想要什么以及應該如何組織文字。而專家只能猜想讀者想要了解什么以及文字應該如何組織。  一個典型的反模式就是當員工要離開公司時，經理請他們在剩余的這段時間里將他們所知道的全部知識都寫成文檔。對大多數人來說這更像是一種懲罰而不是增值的工作。 ### 實踐五——結合可視化元素 盡管文檔應該盡量簡潔，不過當層次結構更加深入，在葉子層級的文檔可能需要稍長一些并且應該包含更多細節。如何能夠在不失去讀者的前提下完成這項工作？不要把文檔寫的像一篇科學報告一樣，要用科普雜志那種更容易理解的風格，包含足夠多的可視化元素和簡短易讀的段落。 增加可視化元素能夠幫助文檔使用者快速找到他們所需要的知識。就像讀報紙一樣，圖片會更吸引讀者的眼球。  用圖片幫助讀者找到合適的段落 ### 實踐六——讓文檔易于維護 寫好文檔的最大挑戰就是一直讓文檔處于最新狀態。 這需要一些訓練和一條簡單的Boy Scout規則，“總是讓營地比你發現它時更整潔。”在文檔中這就意味著：如果文檔沒有提供給你所需要的信息——只要你一找到正確信息就盡快把它更新到文檔中。 所做出的修改與相應的文檔記錄之間距離越遠，保持文檔更新的可能性就越低。代碼中的注釋距離修改更近，所以相對來說就比在另外一個工具中記錄的文檔更有可能被更新。如果用wiki記錄文檔，很容易就可以將代碼中的注釋集成到wiki中。 如果文檔難以更新，或者不能在發現問題時及時更新，就很可能不會被更新。使用可以更容易更新或甚至可以同步更新的工具。圖片也是一樣，因此確保要使用一個可以在工具中直接創建和更新圖片的工具。帶有PlantUML擴展的MediaWiki和帶有Gliffy插件的Confluence就是兩個比較好的例子。 ## 結果 當在另一個城市工作的新團隊需要修改之前由我們的部門維護的代碼時，我們的文檔接受了真正的測試考驗。一個簡短的介紹和一封包含指向文檔區域的鏈接的電子郵件就是我們之間唯一的接觸，而讓我們相當驚奇的是這也是所需要的全部接觸。我們成功達成了目標。我們有了可以快速方便地創建和維護的文檔，而且這些文檔也能夠有效地幫助使用者找到他們所需要的答案。 希望我們的規則和實踐能夠幫助你創建更好的文檔。 祝你好運！ 免責聲明：標題中的“精益”與汽車制造商豐田無關。我所指的是形容詞精益（含義：高效、無浪費）。 感謝Ellen Gottesdiener的支持和幫助。感謝Jonas Boeg?rd，Henrik Rasmussen和Igor Soloviev的好主意。同時感謝Mia Starck和Yassal Sundman在語言方面的幫助。 注：在第一段中所提及的“知識、知識還是知識”指的是：領域知識（了解業務）、系統知識（了解系統的領域和架構）和即時的產品需求知識（與我們目前正在創建的功能的相關知識）。本文中所描述的文檔化方法最適于領域和系統知識，并且可以在這兩者之間建立橋梁。 ## 關于作者  [**Tomas Bj?rkholm**](http://blog.crisp.se/author/tomasbjorkholm)在瑞典斯德哥爾摩的Crisp公司擔任敏捷方法的教練和訓練員。他對不斷成長的團隊，特別是大型企業中的團隊，有著巨大的熱情。他的使命是讓敏捷方法更易于理解和采用。Tomas著有兩本著作，瑞典語版本的《敏捷方法指南》和即將出版的《30天學會Kanban開發》。 **查看英文原文：**[Lean Documentation](http://www.infoq.com/articles/practices-lean-documentation)