👉 目錄
1 用什麽載體
2 需要寫哪些文件
3 怎麽寫好文件
4 文件的維護
5 推薦閱讀書籍
程式設計師最討厭兩類人，一類是不寫文件的人，一類是讓自己寫文件的人。但其實，一篇上下文詳盡、邊界清晰的文件，能夠前置性地解決很多問題，避免因為資訊差而帶來的各種來回追問、扯皮。
寫技術文件是開發者的義務，它和寫可讀程式碼一樣重要，它也可以體現個人做事態度、邏輯思考能力。本篇文章作者將體系化地教會你，如何寫文件，如何寫好文件。
01
用什麽載體
持久沈澱的文件：建議使用可以被多人看到、可以被檢索的知識庫工具，譬如：公司內的 wiki 或者歸屬於組織的知識庫。不建議使用私人文件，或者 word 等無法規模化傳播的工具。
短時間多人協作的文件：首選騰訊文件之類的線上多人協作工具。
整體建議：評審、共建類的文件，可以采用騰訊文件，最終定稿之後使用騰訊文件知識庫或者其他長久儲存工具。
02
需要寫哪些文件
文件是高效溝通、高效協作、知識沈澱、知識分享的工具。鼓勵寫文件，但也不推薦事無巨細的流水賬式寫文件。這些情況下需要寫文件。
模組的整體架構設計文件，譬如：【檢索引擎架構設計詳解】、【檢索內核整體設計】、【線上檢索系統設計】 、【內容架構重構方案】 等等；
模組的關鍵功能設計文件，譬如：【檢索引擎打分排序設計】、【檢索引擎效能評測框架】 等等；
通用經驗沈澱，譬如：【時間戳轉換時間字串導致服務卡死】、【流水線構建說明手冊】、【GCC8 編譯最佳化 BUG 導致的記憶體泄漏】 等等；
計畫經驗總結，譬如：【檢索引擎系統升級計畫總結】、【檢索引擎內核建庫階段效能最佳化】、【內容架構重構計畫總結】 等等；
給其他開發者提供開發框架文件，譬如：【檢索內核 C++ 打分外掛程式開發及使用文件】、【內容接入系統算子開發手冊】 等等；
提供給使用者的功能介紹文件，譬如：【快速入門——檢索引擎接入說明】、【force 召回幹預使用說明】 等等；
復雜 case 排查的總結文件，譬如：【文件入庫時效性滯後排查】、【未召回相關文件排查】 等等；
調研總結文件，譬如：【ES 檢索獲取匹配詞方式調研】、【Lua 外掛程式效能調研】 等等；
新人入門類文件，譬如：【檢索引擎新人大禮包】、【從入職第1天到第1個需求】、【搜尋中台開發入門手冊】 等等；
總的來說，對多個讀者有價值的文件，才值得一寫。
03
怎麽寫好文件
3.1 文件樣版
文件的內容、結構決定了文件的品質，如無特殊說明，技術文件應該采用固定的樣版編寫。當前我們團隊已有的技術文件樣版包括：
【樣版】後台串講文件樣版
【樣版】後台效能評測文件樣版
【樣版】後台架構評審文件樣版
【樣版】技術產品 Case 調查總結文件樣版
【樣版】Case Study 樣版
3.2 排版格式
3.2.1 目錄規範
內容超過一屏的文件，必須有目錄。
目錄必須有數位序號。
3.2.2 撰寫者和編輯者規範
文件必須有 owner，也必須允許開放協作，要求在文章開頭插入文章的主要作者（撰寫）和參與編輯作者（編輯）。
例子：
3.2.3 中英文/數位/標點規範
規範細則：
https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md
核心要點：
中文與英文/數位之間需要增加空格。
數位與單位之間需要增加空格。
全形標點與其他字元之間不加空格。
使用全形中文標點。
3.3 內容組織
3.3.1 核心原則
目標：讓讀者⾼效地獲得預期資訊。
特點：準確、完整、清晰、聚焦。
關鍵詞：簡潔清晰、內容單一、完整準確、有層次、面向讀者。
3.3.2 呈現工具
如果有些步驟比較復雜，建議使用 gif 圖，比貼圖片更詳細，又不會像視訊那麽重。推薦 ScreenToGif 工具，支持錄屏 gif，還可以編輯每一幀，加上文字說明。
3.3.3 合適的粒度
文件應該避免粒度過粗，導致內容銜接不上（不完整）；也避免粒度過細，影響閱讀效率（不簡潔）。粒度的粗細程度，根據文件將要面對的讀者型別而定。
3.4 技術評審文件建議
技術評審文件是我們日常寫得較多的文件，下面舉兩個例子。
3.4.1 從 0 開始搭建的架構
按照金字塔原理，層層遞進，思路如下：
目標和背景，描述清楚為什麽你要做、要做成什麽樣。
整體架構，給出架構的整體檢視，包括：功能架構圖、模組架構圖。
方案細節，以功能架構圖、模組架構圖為藍本，介紹詳細設計。
方案權衡，行業是怎麽做的，為什麽選擇這個方案。
工作排期，給出開發人日，什麽時候開始，什麽時候完成。
其它，根據業務特點，需要給出來的一些附加資訊，譬如：調研報告、參考資訊等等，當內容比較多時，獨立放到另外一個文件中。
3.4.2 對已有功能點的最佳化
按照金字塔原理，問題--> 問題拆解 --> 解決方案分類歸並，思路如下：
背景/提出問題：描述清楚為什麽要做最佳化。
發散方案：可以發散的提出各種解決方案，也可以是對上面問題的進一步分析，行業方案對比也放在這裏描述，除非內容非常多需要單獨放一個文件。
收斂方案：已經將方案明確下來，這裏只探討明確下來的方案細節，可以是有唯一方案，也可以是有多個方案備選。
工作排期：
有時候在【1. 背景/提出問題】這裏提出問題的同時就已經包含了解決方案。
必須圍繞著問題展開討論，緊貼問題，不要把跟主題不相幹的內容放到分析裏，也不要給出一個泛泛而談的問題，問題太泛會導致分析沒有針對性，如果一個問題點太大，需要拆小了分析。
04
文件的維護
文件是跨越時間限制的交流，而時間也可能讓文件過時，因此文件需要持續維護。
4.1 owner 制度
單篇文件，由文件 owner 負責維護，其他同學如果有發現錯誤，也可以隨時更新，文件 owner 負責整體稽核。系列文件，由方向負責人整體承擔文件的品質。
4.2 例行更新和按需更新
文件維護和程式碼品質維護一樣重要且耗費人力。基於投入產出比的考慮，通常建議將更新分為兩種型別。一種是必須及時更新的，譬如：技術產品對外的介面文件，需要結合叠代進度在每次技術升級時例行更新。另一種是讀者不多，更新滯後影響較小的，譬如：給團隊新人閱讀的新人手冊，可以在有新人入職時再更新。
05
推薦閱讀書籍
【金字塔原理】
-End-
原創作者｜吳 銀 光
需要文中推薦的這本書可以聯系小編：
加小編 好友 ，備註"金字塔原理"
