我們一直針對項目文檔有一種矛盾的疑惑，自己不喜歡寫文檔和不喜歡別人沒有寫文檔。我們都知道項目文檔很重要，但是我們總是在項目中短期高估文檔的重要性，長期低估文檔的重要性；結果口號喊得很響，要重視文檔，要寫好文檔，要多些文檔，但是在項目推進中，總有比文檔優先級更重要的任務，文檔總是被退後，導致項目文檔缺失、老舊、無人維護。
我總結了下程序員爲啥不愛寫文檔，首先不知道怎麼寫，其次太忙沒時間寫或者懶得寫，程序員忙的時候情有可原，不忙的時候也很少去寫文檔，寧可去想代碼怎麼重構，其實還是太懶；敏捷開發不用寫文檔？這個是大家都存在的誤區，敏捷開發從來沒有否認文檔的價值，只是更重視“工作的軟件”。
爲什麼要寫文檔？寫文檔，對個人、項目和團隊非常重要，首先幫助寫文檔的人理清楚思路，因爲寫作的過程，就是一個思考的過程，寫文檔，可以讓我們在寫代碼之前，梳理清楚思路，想清楚整體架構，如果一開始就開始寫代碼，會陷入技術細節中，忽略了整體結構；其次先寫文檔，會拋開代碼細節，站在全局思考，每個模塊之間的依賴關係、存在安全隱患，這些都需要去討論諮詢、查詢資料、反覆縝密思考才最終寫出來，其實真正的寫文檔障礙是沒有想清楚，心中只有一些未成型的混亂的想法和概念，我們必須努力把模糊的想法確定化和具體化，換個角度，如果我們連文檔都寫不出來，還能指望代碼寫的好麼？
寫文檔有哪些好處呢？
1.便與未來的維護和交接
“好記性不如爛筆頭”，存在腦子裏的內容是不可靠的，一個正常的項目組，如果要長期維護，就需要有一定的文檔，記錄設計、操作流程、配置環境等。
2.團隊更好的協作溝通
團隊成員間通過文檔更好的溝通，例如產品設計雛形期會有產品設計的評審會議，基於文檔，項目成員一起參與其中討論。
如何寫好文檔？
1.從模仿開始
“依葫蘆畫瓢”，學習別人的文檔格式，
2.從小文檔開始
3.從粗到細，迭代更新
我們小時候寫作文都是要求提綱挈領，先列提綱，把基本結構梳理清楚，然後寫PPT，PPT好處是不用太多文字，列個一二三，畫幾張圖，就是簡單文檔，主要PPT是拿來收集反饋，然後一篇文檔的骨架就搭好了，剩下細節補充。
爲什麼不一開始就寫很細的文檔，因爲太難寫，要花很多時間精力，而且收集反饋的過程中會有很多修改，寫的越細無用功越多，最後甚至會因爲不想改文檔而牴觸不同的意見。
從粗到細迭代一開始是爲了梳理清楚大概思路，然後確定基本細節。
1.基本的畫圖技巧
"字不如表，表不如圖，一圖勝千言"；用好畫圖軟件Visio、PowerPoint、Keynote、OmniGraffle等，比較常用的圖有線框圖、流程圖和時序圖
2.線框圖
線框圖用簡單的方框代替功能、模塊、服務，用箭頭表示關係或者數據流向。看看Twitter當前的緩存方案：
例如Netflix的賬單系統架構圖
- 流程圖
流程圖表示各種不同條件下的邏輯路徑，重點在於梳理清楚邏輯關係，各個關鍵節點不同條件下的走向。
例如重置密碼流程圖
- 時序圖
時序圖表示不同對象之間發送消息的時間順序，涉及通絡通信中特別常用，重點要清楚所有涉及的對象或者服務，以及消息發送的先後順序。
例如註銷登錄過程的時序圖
- 各種格式截圖
軟件UI、交互設計效果、數據趨勢圖、數據統計圖直接截圖配上箭頭、文字。
還有，不需要過度追求文檔的花哨，把大量時間浪費在寫文檔上，我們一直推崇敏捷宣言的觀點，文檔很重要，但工作的軟件高於詳盡的文檔，平衡最重要。好的代碼格式、良好的註釋、完善的單元測試代碼很大程度上代替針對代碼而寫的文檔。
我極力推薦Markdown文檔格式，讓我們更專注於內容而不是根式，後續會專門弄一個Markdown的介紹文檔。
最後總結就是，文檔的寫作要多練習，寫的越多，就越熟練。