在工作中，文檔對我們的重要性不言而喻。簡單的來說，我們寫文檔的目的有3點：
第一，是爲了給自己看，工作過一段時間之後我們自己也會忘記關於當初所編寫的代碼、所做的實施操作是什麼，那麼爲了能夠讓自己的大腦快速恢復場景，有必要將當前發生過的事情用文檔的形式記錄一個“快照”，因此我們正確理解文檔的作用，首先就是一個快照。
第二，是爲了給別人看，無論是項目要碼人還是準備要在未來晉升，文檔都是可以用來節約你時間的最好工具，舉個例子來說，如果你把剛剛加入項目組的新人拉到一邊不厭其煩的去講這個項目的前世今生，不僅你會煩，聽的人也會犯困。口述的知識傳遞量畢竟有限，如果對方不做筆記，或者講述者忘記了一些細節，到時候溝通成本將會成指數級增加。那麼一篇好的文檔發送給別人，就可以降低你的溝通成本。
第三，是爲了技術或者技能提煉或升級。寫文檔寫的多了，便自然會發現相似文檔中的套路，比如實施過程中需要建立表空間，每一次寫文檔的時候如果都加上了，寫文檔的人也會覺得煩，於是便專項提煉出“如何按標準建立表空間和用戶”的文檔，以後再有類似操作，後續的文檔完全可以寫：“請參見《如何按標準建立表空間和用戶》”，這就是技能提煉。如果突然有一天發現知識庫中有幾百篇實施操作或者技術文檔是講類似的操作，則可以將這種操作昇華爲方法論（沒有大量實踐經驗直接拍腦袋想出來的方法論往往都會以失敗而告終），規避各種疑難雜症，甚至從中發現普適性的問題（比如每一個項目都要配置各個服務IP地址，非常麻煩），從而迸發出創造力，將普適性問題解決（比如需要都配置服務IP地址，還要注意客戶網絡環境不能變，因此爲了解決它，想到了用服務發現來解決IP地址漂移的問題），從而實現技術升級。
1、先用5分鐘列出個12345
我們使用的工具可以是Word，也可以是Markdown編輯器，無論是什麼樣的工具，我們都可以通過設想個12345來解決：第一是什麼，第二是什麼，第三是什麼……。這種思維屬於結構化思維，如果暫時想不到，我們可以不妨用這種思維模式來擴展一下：我們想要做什麼？怎麼去做？最終結果應該如何？
這就和人生三大哲學問題是一樣的：我從哪裏來？我是做什麼的？我又要到哪裏去？
比如我們要寫一篇需求文檔，一般套路是：1、需求描述；2、流程設計（或原型設計）；3、實施目標
再比如我們要寫一篇系統詳細設計文檔，一般套路是：1、系統設計目標；2、架構設計；3、原型設計；4、流程規則；5、安裝部署
總的來說，文章應當符合總分總結構，即總覽、分述、總結。
在Word裏有標題的設置，我們可以先列標題1（即1級標題），然後再根據每個標題列出來標題2（即2級標題） ，通過標題的設置，很快就可以建立起一篇文檔的脈絡。
我們所接觸的80%的文檔其實是不用列二級標題的，如果文檔的頁數超過10頁，則建議將二級標題列出來，同樣也是採用列12345的方式。比如說流程設計我們按系統角色的維度擴展開，可以寫成：1、系統管理員操作流程；2、租戶操作流程；3、訪客操作流程；4、審計人員操作流程
切忌一篇簡單的文檔把它細分複雜了，爲了方便閱讀，一定要把文檔寫簡答了。講一個如何處理ORA-00119的報錯問題，標題就是以報錯編碼爲標題，比如“解決Oracle數據庫ORA-00119報錯”，把解決的領域和具體報錯信息作爲標題方便查找。然後大綱寫：1、問題產生的過程；2、處理方式；3、驗證
一個簡單的三段論就可以把ORA-00119講透徹
2、用20分鐘把每件事情講的恰到好處
列完大綱之後，我們就要對文檔的內容進行填充了。這裏面我們要把握好文檔的字數和文檔的度量。畢竟文檔首先是要給自己看的，寫的太複雜也並不會有人給午飯加雞腿，打字還蠻累的對不。所以如果一篇文檔是寫給程序員的，我們就假定這個程序員一定具備了基本的環境部署能力、代碼閱讀能力，因此就沒有必要將大篇幅的代碼粘貼到文檔中讓其他程序員來看，只需要提取最爲關鍵的部分即可。比如講JDBC如何動態獲取字段的文章，我們就簡單的說：在獲取到ResultSet對象之後，調用getMetaData方法可以獲取字段元數據信息，裏面就包含了字段名，用法詳見代碼com.yangruoyu.Demo，這個時候如果再講JDBC是什麼、DriverManager又是什麼、怎麼建立PreparedStatement，或者乾脆把200行代碼全粘上（如果是50行以內直接能跑，粘上倒也無妨，反而更直觀），顯然是不合時宜的。
再比如文檔要講一個需求，給客戶看的話不要提數據庫、字段、時間複雜度，直接說要做什麼、我們會把界面做成什麼樣子即可。因爲這篇文檔我們的目的是爲了讓客戶短時間看明白，同時做出反饋，及時告知我們是不是他們最初想象的那樣子。
同樣還是需求文檔，給程序員看的話，就不要提“隨着科學技術的進步和互聯網的普及”這種套話，直接就說我們要改哪個界面（截一張圖會更好）、涉及哪些字段、字段和字段之間什麼關係、它們是怎麼計算的（涉及流程的建議畫個流程圖）。因爲這篇文檔的目的是爲了讓程序員更快的理解需求，把代碼寫出來。意義固然很重要，但是在項目時間安排上，做這個需求是否有意義得等覆盤再說，當下先要滿足客戶需求。
同樣的，程序員如果寫給項目負責人的部署說明文檔，就不要提用了什麼技術、數據庫字段是什麼。直截了當的就是把程序放在哪個目錄下、是否得重啓系統、如果進到系統界面裏看到了某個東西（給張截圖會更加清晰）就算是這個程序成功運行了。
總之，就是文章中只寫最簡單的、對方最關心的那個點。其餘的內容完全不必寫。
因此大多數文檔可能一張A4紙就能承載。這種文檔無疑是成功的。
爲了能夠描述清楚，文章中的圖片覆蓋率建議在25%左右，可以畫流程圖、原型圖、UML圖、腦圖，甚至是屏幕截圖。總之，一張圖勝過千言萬語，爲了讓其他人能懂，這都是值得的。
腦圖的樣例
3、用5分鐘時間整理
把文檔按時間編碼（比如文件名以20200331_0630開頭，方便按文件名排序，文檔先後順序一看便知）、傳到知識庫（或網盤），然後發給需要的人看即可。寫文檔是個功夫，需要不斷練習。連續寫上4、5篇，寫文檔的感覺就有了。
如果以後有人再問XX產品的架構是怎麼回事、XX的配置怎麼做，一篇文檔發過去，輕鬆又便捷。