技術文檔寫做的道與術

• 世界觀
  • 爲何要寫技術文檔
  • 反駁不須要寫文檔的言論
  • 附議：爲何要看文檔
  • 什麼算好的技術文檔
  • 文檔&寫文檔的定義
• 方法論
  • 基調
  • 結構
    • Introduction
    • Content
    • Terms
    • Setup
    • Body
    • Reference
    • FAQ
    • Appendix
    • ChangeLog
    • ReleaseNote
  • 過程
  • 工具
    • 寫做工具
    • 維護工具
• 總結

文檔的範圍很廣，本文特指 開發人員撰寫的包含基本產品背景和主要技術設計的文檔 。

世界觀

爲何要寫技術文檔

對於這個問題，我我的以爲很容易回答，寫技術文檔能夠幫助團隊完成
當前的信息共享和長期的知識傳承 。對於我的而言，一方面能夠
節省時間 ，
由於避免了回答重複問題，也便於檢索過去的知識；另外一方面能夠 塑造口碑
，好比某次就忽然有個同事給我發消息說個人文檔寫的很好，對新接觸這塊業務的人幫助很大。

某某同事的感謝.

反駁不須要寫文檔的言論

有不少程序員都持有一個觀點：「不用看(寫)文檔，文檔都在代碼裏」，還有一部分人認爲，文檔容易過期，很難跟上代碼的更新節奏，於是沒有必要寫文檔。
凡此種種觀點致使了一個局面就是：
接手業務的時候吐槽別人不寫文檔，交接業務的時候又以爲這東西無需解釋，根本不須要文檔
。
對此，首先我我的認爲涉及代碼細節的部分確實不必寫文檔，可是對於整體的設計和業務的變動是絕對須要寫文檔的。有些人以爲文檔有過期問題，那是由於他們沒有引入版本（ChangeLog）的概念，
過期的文檔自己就是業務歷史的一部分
，我在接手一個業務的時候，經常就須要這些歷史信息來輔助理解。

附議：爲何要看文檔

上週發生了一件趣事，一個產品跟我說，
開發兩句話能說明白的，爲何要看文檔
？確實，問開發能以最快速度準確地獲取信息，畢竟人腦就是一個強大的搜索引擎。可是長期來看有如下問題：

1. 浪費開發時間

2. 開發沒法隨時答覆，浪費本身時間

3. 信息沒法固化、傳承，並且過於瑣碎，浪費團隊時間

通常來講，一份 好的技術文檔
比起開發口述是不會有多餘的理解成本的，甚至更低，由於對於不少信息，圖片能比語言更好地表達。

什麼算好的技術文檔

我認爲 好的技術文檔 的核心是 敏捷 。一方面，好的的技術文檔是
高度可維護的而且常常維護
的，好比新增了一些功能，文檔的做者可以快速更新文檔，文檔的讀者能及時獲取更新；另外一方面，好的技術文檔是
易理解 的，更詳細來講要表述準確、結構清晰、排版美觀、風格統一。

文檔&寫文檔的定義

最後，我想探討下寫文檔究竟是幹嘛？百度百科說：

軟件文檔或者源代碼文檔是指與軟件系統及其軟件工程過程有關聯的文本實體。

那麼寫文檔就是生產這個實體的過程了。但這樣實在過於抽象，根據我最近一年的經驗來看，我更願意將其定義爲
對特定信息進行結構化整理的過程 。

以上就是寫做技術文檔的道了，也就是咱們對於這件事最基礎的世界觀，接下來談術，即基於此執行的方法論。

方法論

基調

在正式開始寫文檔以前，咱們必需要有如下三點認知：

1. 足夠了解 ：
   咱們要爲某個模塊寫文檔，前提必定是咱們對這個模塊足夠了解，只有基於此，咱們的文檔纔是有價值的，不然只是信息垃圾。

2. 換位思考 ：
   即使有了交接文檔，咱們也常常須要去詢問交接人，這種狀況家常便飯，究其本質，是由於不少時候咱們都是站在本身的角度、按照本身的理解來寫文檔的，可是讀者的信息背景和咱們是徹底不同的，咱們以爲理所固然的可能他們一無所知，因此寫做文檔必需要有足夠的換位思考的意識。
   文檔是寫給別人看的，不是寫給本身看的 。

3. 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網頁，編輯體驗確定也比不上本地本身配置的編輯器。固然，術沒有絕對的優劣之分，也要看本身是否合適。

總結

以上，最近關於技術文檔寫做的一些思考。歡迎交流指正。