如何寫好項目文檔

引子

• 有太多的程序員（包括很多資深的程序員）不會寫文檔

• 有太多的項目沒有（完整的）文檔

• 即使有文檔，這些文檔達標了嗎？

• 你對文檔有正確的認識嗎？

• 你會寫文檔嗎？？

• 軟件項目的文檔是可有可無的嗎？

目錄

• 項目文檔的重要性
• 文檔的目的：
  • 提高溝通的效率
  • 提升對“思考過程”的管理
• 項目中，超過50%的時間用於溝通
  • 提高溝通的效率非常重要
• 溝通的方式
  • 口頭， 文檔， 代碼
• 對“思考過程”的管理
  • 項目中常常面臨數不清的問題（“線頭”）
  • 理清問題，挑出重點， 深入挖掘

常見的誤區

• 寫文檔是浪費時間？ 沒時間寫文檔？

• 文檔本身也是產出： coding 的時間少於30%。
• 寫文檔是整理思路的過程：打字的速度應該快要思考的速度
• 沒有文檔，後期會花費更多的維護成本

• 沒有需求和設計文檔就開始寫程序？

• 修改文檔，比修改代碼的成本小的多。（）

• 這是個簡單的項目/問題，不需要文檔？
  • 項目的延續時間和複雜性往往超出預期
  • 早期的“偷懶”， 往往在後期會付出代價

常見的問題

• 沒有接口文檔：多人協作出現問題
• 需求文檔沒寫好：
  • 多次反覆討論同樣的問題
• 沒有系統總體架構文檔：

• 每個人都需要重新看代碼，還不一定能看請

• 缺少文檔：

• 新人無從入手
• 人員變動時、不好交接
• 團隊內部溝通效率很低
• 自己過兩個月後，痛苦的回憶之前的思路

什麼時候需要些文檔？

• 必須的文檔

  • 需求設計文檔：需求， 重點，取捨過程
  • 接口文檔： 函數， 參數， 返回值
  • 邊界性的算法文檔： 思路， 關鍵點
  • 系統總體框架： 全局的思路

• 凡是不那麼“顯而易見”的地方，最好都留下文檔

• 文檔中不僅僅留下設計的結果（what), 也要留下思考的過程（why）: 留下決策的依據，便於後面的工作

• 文檔不是寫完代碼後補出來的！

  • 文檔是設計過程中使用的工具、和設計過程的結果

文檔書寫規範

• 封面
  • 編號（用於Reference），項目，版本號
• 歷史說明

• 修訂人、修改日期、修改說明

• 字體

• 宋體，五號字， 單倍行距

• 文檔結構

• 分層次的標題

文檔的存放

• 這裏推薦一個比較實用的做法

• 你可以根據自己的情況來設計一個存檔方式

• 將文檔（word格式)保存在svn上

• 容易看到本地和遠程的不一致

• 在wiki上建立文檔的索引

• 便於看請全局的情況（內容分佈，時間分佈）

文檔內容的書寫

• 文檔的格式
• 文檔的邏輯
• 文檔的評價
• 文檔的書寫方法

文檔的格式

• 格式表現的是一種邏輯

• 可能的邏輯關係： 總-分，遞進， 並列， …

• 標題
  • 標題是否表達文檔的內容
  • 標題是否和文檔的內容相符合
  • 各層標題所構成的提綱，是否能清晰反映文檔的內容？
• 段落
  • 段首一定要有縮進
  • 段落不要太長
  • 注意每段的第一句話
  • 每段內的多句話應該有一定的邏輯

文檔中問題的劃分

• 選擇合適的角度

• 從不同的角度看到的東西是不一樣的（類比：汽車不同角度的riew）

• 角度的說明： 說明劃分問題的出發角度
• 注意聯繫： 子問題之間的聯繫
• 是否是一個獨立的問題

• 切分問題是否準確

• 是否是一個重要的問題

• 決定寫作的詳略。

選用合適的表述模式

• 不同種類的問題，有不同的模式
• 分析和解決一個問題： 提出問題，分析問題，解決問題
• 提出一個實現的建議： 出發點（目的），手段，工作量估計，收益的估計
• 系統的設計： 模塊，功能，過程
• 程序的設計： 數據，函數，模塊，調用過程，系統結構

文檔的評價

• 文檔是寫給別人看的！
• 能否讓讀者在5分鐘內看懂
• 能否做到問題清楚、重點突出、邏輯清楚？
• 能否做到言之有物： 不要死套格式
• 能否做到言簡意賅：不要說廢話
• 能否避免造成別人的誤解

• 不要說模棱兩可的話
• 要注意自己的表達是否通俗（有太多人說“自己才懂的方言”）

文檔的書寫方法

• 拉提綱，自頂向下
  • 大的標題下列出子問題，再對每個子問題逐步展開
• 反芻

• 感覺（一句，一段，甚至整個文章的結構）不好之後要及時修改
• 提高自己寫文檔的能力

• 讓重要的內容醒目

• 標題： 段首第一句話：
• 加重、有顏色、或者帶下劃線的文字

文檔中配圖的指南

• 要明確這個圖片的目的

• 只能展現1-2個（最好是一個）主要問題
• 只能說明一個層次上的問題

• 要明確圖片中傳遞信息的重點
• 要注意圖片中面積的使用

• 可能錯誤：太多空白的區域，說明的文字過小

• 圖片最好能獨立說明一個事情

• 同時太多的關注點 =》 失焦

• 對於圖片中不能明確表達的地方，需要在圖片周圍的文字部分給出輔助的說明

文檔的review

• 有太多文檔的review是無效的！
  -Q（leader): 這個文檔你reciew過了， 爲什麼質量還這麼差？！
  -A（reviewer)：這個文檔的內容我也感覺是模模糊糊的…
• 甚至有很多文檔寫出後，根本就沒有被（仔細）看過

• 寫這樣的文檔有什麼用？

• 文檔的review是一次在大腦中的“重放過程”

• 嘗試follow作者的思路，看看是否可以走通
• 是否有遺漏的內容

• 文檔review的產出

• 在文檔中插入comment
• 直接對文檔進行修訂
• Word提供了很好的功能，你也可以選用其它工具

怎麼提高寫文檔的能力

• 一個普遍的誤區

• 我對這個項目都非常清楚，我只是不會寫文檔
• 你錯了！寫不好文檔的根本原因是沒有想清楚！

• 提高寫文檔的能力的本質

• 最根本還是提高分析問題的能力， 提高設計系統的能力

• 多看好的文檔

• 好的教科書（不僅僅告訴你what, 而且分析why,要注意看分析過程）
• 好的論文（很多發表的（尤其寫系統的）論文，可能原來就是一個設計文檔）

• 多些（自己給自己挑毛病。類似金庸筆下週伯通的左右互搏）
• 多相互review(看一遍別人的文檔，也是很好的訓練)