十大技巧助你成為文檔聖手

        去年七月，在 OKFestival 渡過一整周后，我設法抽出足夠的精力出席 Write the Docs Unconferences 會議。我僅參加了一天，但是因為 Paul Adams 在此次會議中提出「我們應該提出一些措施來幫助文檔團隊更具創造性「而很有價值。Paul Adams 是一名自由軟體倡導者以及 KDAB 公司工程類的董事。

• 學會批註風格並堅持下去

你所學習的批註語言要讓你的團隊考慮是否能滿足你所有的需求，尤其是要選擇能毫不費力就能從批註轉換到正式輸出格式的工具。對於編輯工具來說那是無所謂的，可以讓他們選擇自己喜歡的文本編輯器或著編輯一份維基（wiki）。這取決於團隊的表現。

• 總是使用轉換輸入的工具鏈

工具的關鍵在於總能自動的產生輸出。最理想的是一條命令就能多次產生你所需要的各種格式的文檔。

• 將最後的文檔格式按你的用戶需求生成

大多數項目以 HTML 網頁文檔或者一份 PDF 文檔結束。

• 為文檔定義一份風格指南並按指南執行

定義所有的事情，包括語言細微的差異，標題的寫法，或者說在整篇文章中代詞的用法等。

• 總是要有翻譯

也許你現在不需要翻譯，但之後可能會需要。不是每個人都說英語或漢語。最終你都會想到要翻譯。我們曾經就想過將文檔按日語翻譯。當你在使用標註和工具鏈的時候最好就考慮翻譯。（請看「文檔翻譯 5 技巧」）。

• 翻譯要基於原始文檔

假如你是用英語寫文檔，那麼讓你其他所有的翻譯都基於英語。這樣在修改文檔時能保持一定簡便。

• 制定語言特有風格指南

這點既要求程序性語言也要求自然語言。某些語言在寫辦公型文檔可能出現部分代詞的特殊用法。形成團隊的一份程序語言特有風格指南非常有利於保持文檔統一。

• 對文檔做質量檢驗

如果在你的文檔中有使用說明，它們就需要被檢查，如是否存在單個字元的改變破壞使用說明的問題。另外，要回顧新的文檔。這一點對安裝說明和 API 文檔尤其重要，因為這類文檔很容易出錯並令最終的用戶感到沮喪。

• 更新和存檔文檔要有規則

如果你的文檔過時了，將其存檔並從移除搜索引擎檢索。當新的文檔有老版本中不存在的特性時，一定要有一個清晰的通知。如果文檔是你代碼的一部分，而且只有在發布新版本時文檔才會被更新，那麼針對於老版本的補丁文檔也是應該要有的。

• 文檔必須要有反饋機制

最間單的方式就是為文檔添加一個漏洞跟蹤反饋分類。

總而言之，寫文檔最重要的是建立一種文檔文化。文檔不是事後的一份隨想，是需要一個逐步修改發行的過程。一個僅能通過文檔團隊才能知道所需要文檔新特性的過程。雖然事實上，如果能找到一位開發者樂意支持文檔項目那可就再好不過了。但我更願授權給他們而不是麻煩他們。因為這樣做更有用，否則可能加重他們的負擔。舉個例來說，不要把文檔相關的漏洞歸咎於他們，並給他們干涉文檔特性的權利。因為他們正處於文檔編輯中。

看到這裡的你是否想到了其他建議呢？如果有，就請在下方評論讓我們知道吧。

原文鏈接：http://opensource.com/business/15/7/10-tips-better-documentation