技術文件寫作的道與術
- 世界觀
- 為什麼要寫技術文件
- 反駁不需要寫文件的言論
- 附議：為什麼要看文件
- 什麼算好的技術文件
- 文件&寫文件的定義
- 方法論
- 基調
- 結構
- Introduction
- Content
- Terms
- Setup
- Body
- Reference
- FAQ
- Appendix
- ChangeLog
- ReleaseNote
- 過程
- 工具
- 寫作工具
- 維護工具
- 總結
文件的範圍很廣，本文特指 開發人員撰寫的包含基本產品背景和主要技術設計的文件 。
世界觀
為什麼要寫技術文件
對於這個問題，我個人覺得很容易回答，寫技術文件可以幫助團隊完成
當前的資訊共享和長期的知識傳承 。對於個人而言，一方面可以
因為避免了回答重複問題，也便於檢索過去的知識；另一方面可以 塑造口碑
，比如某次就突然有個同事給我發訊息說我的文件寫的很好，對新接觸這塊業務的人幫助很大。
某某同事的感謝.
反駁不需要寫文件的言論
有很多程式設計師都持有一個觀點：“不用看(寫)文件，文件都在程式碼裡”，還有一部分人認為，文件容易過時，很難跟上程式碼的更新節奏，因而沒有必要寫文件。
凡此種種觀點導致了一個局面就是：
接手業務的時候吐槽別人不寫文件，交接業務的時候又覺得這東西無需解釋，根本不需要文件
。
對此，首先我個人認為涉及程式碼細節的部分確實沒必要寫文件，但是對於總體的設計和業務的變更是絕對需要寫文件的。有些人覺得文件有過時問題，那是因為他們沒有引入版本（ChangeLog）的概念，
，我在接手一個業務的時候，常常就需要這些歷史資訊來輔助理解。
附議：為什麼要看文件
上週發生了一件趣事，一個產品跟我說，
開發兩句話能說明白的，為什麼要看文件
？確實，問開發能以最快速度準確地獲取資訊，畢竟人腦就是一個強大的搜尋引擎。但是長期來看有以下問題：
浪費開發時間
開發無法隨時答覆，浪費自己時間
資訊無法固化、傳承，而且過於瑣碎，浪費團隊時間
一般來說，一份 好的技術文件
比起開發口述是不會有多餘的理解成本的，甚至更低，因為對於很多資訊，圖片能比語言更好地表達。
什麼算好的技術文件
我認為 好的技術文件 的核心是 敏捷 。一方面，好的的技術文件是
的，比如新增了一些功能，文件的作者能夠快速更新文件，文件的讀者能及時獲取更新；另一方面，好的技術文件是
易理解 的，更詳細來說要表述準確、結構清晰、排版美觀、風格統一。
文件&寫文件的定義
最後，我想探討下寫文件到底是幹嗎？百度百科說：
軟體文件或者原始碼文件是指與軟體系統及其軟體工程過程有關聯的文字實體。
那麼寫文件就是生產這個實體的過程了。但這樣實在過於抽象，根據我最近一年的經驗來看，我更願意將其定義為
對特定資訊進行結構化整理的過程 。
以上就是寫作技術文件的道了，也就是我們對於這件事最基礎的世界觀，接下來談術，即基於此執行的方法論。
方法論
基調
在正式開始寫文件之前，我們必須要有以下三點認知：
足夠了解 ：
我們要為某個模組寫文件，前提一定是我們對這個模組足夠了解，只有基於此，我們的文件才是有價值的，否則只是資訊垃圾。換位思考 ：
即便有了交接文件，我們也經常需要去詢問交接人，這種情況屢見不鮮，究其本質，是因為很多時候我們都是站在自己的角度、按照自己的理解來寫文件的，但是讀者的資訊背景和我們是完全不一樣的，我們覺得理所當然的可能他們一無所知，所以寫作文件必須要有足夠的換位思考的意識。
文件是寫給別人看的，不是寫給自己看的 。MECE原則 ： 簡單來說就是 相互獨立，完全窮盡
，這個思想可以指導我們對文件結構進行組織。下面給出一個參考。
結構
本章節討論了一份技術文件應該具備的各個單元，可以作為今後技術文件寫作的框架或者Checklist。
Introduction
簡單介紹專案背景資訊，如下面是我為某個專案寫的 Introduction ：
Content
目錄，目錄是結構的直接體現，必須有，一般文件寫作工具都能自動生成：
Terms
術語解釋，很多業務會衍生一些特定詞彙，如“白條卡”、“大圖卡”等，都是有特定語境的，需要單獨解釋。
Setup
如何執行這個專案，一般開源專案都會有，如果是SDK文件也常常有接入文件，就是這個模組。
Body
這部分就是文件的主體部分，具體結構需要視內容而定，有以下通用規則
一圖勝千言，如Android的架構圖、Actvity的生命週期圖，比任何語言都好使。
Demo勝千言。
對於具體的格式規範，推薦閱讀 ruanyf/document-style-guide:
中文技術文件的寫作規範。
Reference
相關需求單：比如某個業務所有相關的需求單都放在這裡，方便其他人更進一步瞭解背景，也方便自己查詢。
參考資料。
這部分也可以放在附錄裡面，見下圖。
FAQ
其他人經常問的問題，遇到就記錄在這個模組，不斷補充，日趨完善。
Appendix
一些比較冗長的資訊可以放在附錄裡面，比如日誌，避免放在正文影響排版和閱讀。
ChangeLog
變更日誌，一般開源專案都會記錄每個版本的重要變更。
ReleaseNote
發版日誌，一般開源專案都會有一個單獨的Release頁面。
過程
一般來說，文件寫作的流程如下：
收集資訊、整理框架、實踐結論、寫作文件
。如果前期工作足夠，寫作所花的時間是很少的。
此外，文件完成後，還要注意讀者反饋，以不斷完善自己的文件。
寫一份好的技術文件也不是一蹴而就的，需要不斷打磨，要注意經常去
刻意練習 。
工具
寫作工具
一般來說，只要別人發給我的文件是一份Word文件，我基本就把這份文件排在了最LowB的一檔。對於這種文件，我就想問兩點：
文件有更新怎麼分發給每個需要這份文件的人？
Word格式不相容導致關鍵圖表排版混亂怎麼辦？
一般來說，文件寫作工具有以下選擇：
Word
Pdf
Markdown
Asciidoc
Latex
對於Word/Pdf我是極力排斥的，因為很多文件都是需要更新的，這兩種格式沒法做到
動態更新 。Markdown
比較受開源社群的歡迎，因為它在表達力和簡潔性之間找到了一個平衡點，但是它有一個致命問題就是
無法應付稍微複雜一點的排版
。Asciidoc是我的主力文件工具，很多人不知道Github也是支援這種文件格式的，比如本文就是這種格式的。Asciidoc的語法比Markdown更加複雜，但我認為
犧牲一點時間學習是完全值得的
。最後是Latex，Tex的變種，表達力最強大，可以應付各種複雜排版，一般在學術圈比較流行（尤其是那些複雜數學公式的表達），但我認為放在日常的文件寫作中有點矯枉過正了。
綜上，我推薦Asciidoc。
維護工具
對於文件的管理，我推薦使用Git，像管理程式碼一樣管理文件。
另外我推薦使用一個靜態網站來存放自己的文件，這樣其他同事訪問的時候看到的總是最新的文件了。
另外，公司目前在推iWiki，我覺得iWiki最大的優勢是 許可權控制
，對於一些敏感文件是必須的。但是，比起iWiki的變更記錄，作為程式設計師的我更鐘愛用Git進行管理，此外，iWiki是Web網頁，編輯體驗肯定也比不上本地自己配置的編輯器。當然，術沒有絕對的優劣之分，也要看自己是否合適。
總結
以上，最近關於技術文件寫作的一些思考。歡迎交流指正