學習一個新的工具或者軟件，首選方法是閱讀開發者寫的軟件文檔，因爲TA最清楚怎麼回事；其次是閱讀最新的英文相關使用討論或者介紹，因爲中文的很多資料往往滯後；再次纔是閱讀中文相關介紹，而且一定要謹慎參考認真判斷。評判一個工具好壞的標準之一也是其文檔是否寫的足夠「好」。
因此無論是開發者還是用戶，文檔都至關重要。那到底好的文檔需要包含哪些內容或者應該如何寫出一個儘量好的文檔呢？最近看到一篇英文博客：What nobody tells you about documentation ，以下爲儘量保留作者原意的不完全翻譯版本供你參考。
寫在前面
無論你如何認真地寫軟件文檔，它可能都對你的軟件起不到什麼幫助，除非你掌握了正確的文檔寫作方法。爲了寫好軟件文檔你需要了解一個祕密：「文檔」不是特指某一個內容，而是有四個。
它們是：教程(tutorials)，操作指南(how-to guides)，說明(explanation ) 和技術參考(technical reference)。它們代表了四種不同的目的或功能並且需要用四種不同的方法來寫，瞭解這一點將有助於極大改進大多數軟件的文檔。
一個軟件有多好並不重要，因爲如果文檔不夠好，很多人就不想使用它。
即使由於某種原因（沒有第二選擇）別人不得不用，如果沒有規範良好的文檔，使用者也不會高效地或者按照開發者想要的方式來使用。雖然幾乎每個人都明白這一點，每個人也都知道他們需要一個好的文檔並且試圖創建一個好的文檔，但是大多數人還是失敗了。這並不是因爲他們不夠努力而是因爲沒有找到正確的方法。
接下來我將解釋如何使你的文檔變得更好，不是更加努力而是通過正確的方式。所謂正確的方法其實就是更簡單的方法：更容易編寫，更容易維護。
The right way is the easier way - easier to write, and easier to maintain.
有一些非常簡單的原則可以指導我們進行文檔編輯，但似乎又像是一個祕密很少被人們提起和總結。如果你能夠將這些原則付諸實踐，它就可以使你的文檔變的更好，進而使你的項目、產品或團隊更成功。
原則
好的文檔需要包含並圍繞其四個不同的功能進行構建：教程(tutorials)，操作指南(how-to guides)，說明(explanation )和技術參考(technical reference)。每一部分都有自身獨特的寫作模式，使用軟件的人在不同的時間不同的情況下會需要這四種不同的文檔 。因此，需要圍繞它們明確地來構建文檔並且必須保持獨立和彼此不同。
教程
- 學習爲導向(learning-oriented)
- 可以讓新手輕鬆入門
- 可以理解爲是一節課
如果要打個比方，就像教小朋友怎麼做飯
操作指南
- 目標爲導向(goal-oriented)
- 展示如何解決特定問題
- 是一系列步驟
打個比方就是烹飪書中的一個食譜
說明
- 理解爲導向(understanding-oriented)
- 用來進行解釋
- 提供各種相關的背景
打個比方就像是一篇關於烹飪歷史的文章
參考
- 信息爲導向(information-oriented)
- 描述一個工具的系統方法
- 一定是準確而且完整的
類比的話，可以參考百科全書中的文章
以上這種分類可以使開發者和用戶明白哪些信息在哪裏。它告訴開發者如何寫，寫什麼以及在哪裏寫，使他們免於浪費大量時間來嘗試將想要傳達的信息改爲其他亂七八糟的形式，因爲這四種文檔，每一種只有一個任務。
如果這些文檔沒有明確地展現出自身用處和界限，想要維護一個良好的文檔就是非常困難的。每種類型的文檔要求都與其他三者不同。你一旦理解了這些結構它就能成爲一種非常有用的工具，一方面你可以用它分析自己現有的文檔，另一方面可以瞭解需要採取哪些措施進行改進。
教程
教程是讓用戶通過一系列步驟來完成某個項目的課程。它是你的軟件所必須具備的，用來向初學者展示他們可以用它實現某些目的。教程完全以學習爲導向，進一步講，他們的目標是學習如何使用而不是瞭解你的項目。
此時你是一個老師並對學生將要做的操作負責。在你的指導下學生將執行一系列操作以達到目的。什麼時候結束和進行哪些操作都取決於你，但決定一個初學者應該做什麼非常困難，一方面這些操作和最終的結束點必須有意義，同時對於一個真初學者而言又要可以實現。
現在想想教孩子做飯的例子。你教孩子做了哪道菜其實並不重要，重要的是讓孩子覺得做飯這件事很有樂趣並且有信心，同時還希望自己可以再來一次。通過孩子所做的事情，他將學習烹飪的一些重要事項並且將瞭解在廚房裏使用餐具來處理食物是一種什麼感覺。
使用軟件（做飯）是一個「手藝」問題。它的確是知識，但它是一種實踐得來的知識。當我們學習一項新的手藝或技能時，我們總是從實踐開始。記住，完成教程後學習者應該就能夠理解軟件本身和其餘的那些文檔。老實說，大多數軟件項目的教程都非常糟糕或者根本不存在教程。教程可以讓一個學習者變成你的用戶，錯誤或缺少教程將阻止你的軟件獲取新用戶。不過好的教程很難寫，它需要對初學者有用有意義易於參照且夠強大。
如何寫出好教程
允許用戶通過實際操作進行學習
小時候我們都是通過實踐和嘗試來學習東西，比如說話或走路。在你的軟件教程中學習者需要有事可做，而且他們所做的事情需要涵蓋這個工具大量的操作，從最簡單的操作開始再到更復雜的。
讓用戶走出第一步
不管初學者的第一步是複製粘貼，還是不像一個有經驗的用戶那樣操作，或者甚至不是一個“正確的”使用方式，這些都是可以接受的。初學者的教程與最佳實踐手冊不同，教程的目的是讓學習者開始他們的旅程而不是讓他們到達目的地。
確保教程可以運行
作爲老師你的一個重要工作是激發初學者的信心，有很多途徑可以促成這一點，比如友好的語氣和富有邏輯性的內容與資料等等。但最重要的是你要求初學者做的事必須確實可以做到。學習者需要看到你要求他們採取的操作會產生你答應他們會有的效果。如果學習者的操作產生報錯或有了一個意外的結果那教程就等於失敗了， 即使這不是你的鍋。
當你的學生和你在一起時你可以現場解決問題；如果他們自己閱讀文檔你就不到這一點了。所以必須提前防止這種情況發生，emm，這說起來容易做起來難。
確保用戶可以立刻得到結果
初學者所做的一切都應該是容易理解的。如果他在看到結果之前必須做很多步難以理解的操作那就很糟糕了。每一個操作的效果都應立即展示出來，並且明確它與操作之間的聯繫。教程的每個部分或整個教程的結論必須是有意義的。
確保你的教程可重複
教程必須能可靠地重複，這其實不容易實現，因爲人們使用不同的操作系統，經驗水平也不一樣。更不要說他們使用的軟件或資源很可能在一段時間內會發生變化，比如版本。因此教程需要定期和詳細的測試，以確保它們一直有效。
關注具體步驟而非抽象概念
教程需要具體，圍繞特定的操作和結果展開。引入抽象的概念通常誘惑巨大，但是所有的學習都是從特定和具體到一般和抽象。
提供最低限度的必要說明
不要解釋學習者完成教程不需要知道的任何內容。擴展討論很重要但它不是教程的作用，在教程中這反而是一個會讓學習者分散注意力的絆腳石。只要有最低限度的解釋就可以了，你可以鏈接到文檔中其他地方的說明。
只關注用戶需要採取的步驟
教程只需要專注於學習者手頭的任務。也許你的命令有許多其他選項，或者可能有不同的方法來訪問某個 API。但是現在你的學習者不需要了解那些就能取得進步。
操作指南
操作指南使讀者瞭解解決實際問題所需的步驟。它們是食譜，實現特定的目標。例如如何創建Web表單，如何繪製三維數據集，如何啓用 LDAP 身份驗證。
操作指南完全以目標爲導向。想想一個食譜就可以，它解決了一個具體問題，我們可以假設用戶已經擁有一些基本知識，他僅僅想知道如何實現某些目標。操作指南與教程完全不同，操作指南是對初學者甚至無法提出的那些問題進行的回答。
在操作指南中我們可以假設用戶已經知道如何執行基本操作並使用基本的工具。讓我們開心的是，不少軟件文檔中的操作指南往往做得都還不錯。
如何寫出好的操作指南
提供一系列步驟
操作指南必須包含需要按順序執行的步驟列表（就像教程一樣）。你不必從頭開始而是應該找到一個合理的起點。操作指南應該可靠，但不需要具有教程那樣萬無一失的可重複性。
關注結果
操作指南必須注重實現目標，其它的都會讓用戶分析，與教程一樣，詳細的說明在這裏也不合適。
解決問題
操作指南必須解決特定的問題，也就是「我如何...」。這是操作指南與教程不同的地方：當涉及到操作指南時，可以假定讀者知道他們應該實現什麼但不知道如何實現， 而在教程中你有責任決定學習者需要了解的內容。
不要解釋概念
操作指南不應該進行解釋，這裏不是討論的地方，它們只會妨礙用戶操作。如果解釋很重要請鏈接到該有的地方。
允許一些靈活性
操作指南應該允許用稍微不同的方式來做同樣的事情。它需要足夠的靈活性，用戶可以看到如何應用於與你描述示例略有不同的場景，或者瞭解如何使其適應與你假設略有不同的系統或配置。
該結束就結束
實際的可操作性比完整更有價值。教程需要完整但是操作指南不需要。它們可以在合適的地方開始和結束，也不需要提及所有和主題相關的內容。臃腫的操作指南無法幫助用戶快速獲得解決方案。
認真命名標題
操作方法文檔的標題應該告訴用戶確切的內容並且指明是一個操作指南。比如「如何創建基於類的視圖」就是一個好的標題，但是直接叫「基於類的視圖」就不好了。
參考
參考是工具的技術描述和如何進行操作。
參考只有一個任務就是描述。它們是由代碼決定的，因爲描述的是：關鍵類，函數，API等等，應該列出函數，字段，屬性和方法等內容並列出如何使用它們。
參考以信息爲導向。技術參考可以包含示例來說明用法但它不應該嘗試解釋基本概念或者如何實現通用的功能。參考資料也應該是切中要害的。用烹飪類比，它可能是一篇關於某種食材的文章，描述了它的來源、化學成分和如何烹飪等等。
請注意，描述確實包括瞭如何使用工具的基本描述，比如如何實例化特定類或調用某個方法，或者在將某些東西傳遞給函數時必須採取的預防措施。然而這僅僅是其作爲技術參考功能的一部分而且和操作指南也完全不同。
對於一些開發人員，參考指南是他們可以想到的唯一文檔形式。他們已經瞭解了自己的軟件並且知道如何使用它，所以他們想象其他人可能需要的就僅僅是它的技術信息。參考往往很多軟件也寫得很好，現在它甚至可以在某種程度上自動生成。
如何編寫好的參考文檔
在代碼周圍構建文檔
爲參考文檔提供與代碼庫相同的結構，以便用戶可以同時瀏覽代碼和文檔。這也將有助於維護人員查看缺少參考文檔或需要更新的位置。
始終如一
在參考指南中，結構，格式必須一致，與百科全書或字典一致。
只進行描述
技術參考的唯一任務是儘可能清楚和完整地描述。其他任何事情（解釋，討論，指導，推測，意見）不僅會分散注意力，而且會使其更難以使用和維護。避免使用參考來指導如何實現某種功能，並且不要對概念或討論進行解釋。如果需要，可以酌情鏈接到操作指南說明和入門教程中。
準確
這些描述必須準確並保持最新狀態。工具與描述之間的任何差異都將不可避免地導致用戶誤入歧途。
說明
說明用來解釋、討論和闡明特定的一個主題，它們拓寬了文檔對某一主題的覆蓋範圍。說明是以理解爲導向的。解釋同樣可以描述爲討論。它可以讓你從更廣泛的視角，從更高層次甚至從不同角度闡明它。可以想象一個討論文檔是在閒暇時閱讀的，而不是在瀏覽代碼時閱讀。
通常這部分文檔很少被明確的創建，解釋的片段會分散在其他部分中。其實說明和討論不像看起來那麼容易創建 ，它的主題不是由你想要實現的特定任務定義的（操作指南），也不是你希望用戶學習的（教程），當然也不是具體的函數定義的（參考材料）。
如何寫出好的說明
提供上下文
說明通常需要指明背景和上下文，有時候說明還可以解釋「爲什麼是這樣」，可能是設計決策，歷史原因或者技術限制。
討論替代方案和意見
說明也可以提供一些替代方案或同一問題的多種不同方法，甚至可以考慮並權衡相反的意見。
勿提供技術參考或指導
說明應該做的事情就是文檔其他部分沒有的東西。告知用戶如何做某事並不是說明的任務它也不應該提供技術描述，文檔的這些功能在其他部分中已經完成了。
關於文檔結構
爲什麼分界不明顯？
上文討論的文檔結構很清楚並且很有效，但通常分界沒有那麼明顯，這是因爲文檔四象限中每個象限與相鄰的都會有一些重疊特徵。
教程和操作指南是相似的，因爲它們都關注描述實際步驟；操作指南與技術參考的交集在於它們是在實際工作和編碼時所需要的；參考指南和說明相似是因爲它們關注理論知識；最後教程與說明的共同點是它們在我們進行學習時最有用。如下表所示：
| 學習時最有用 | 工作時最有用 | |
|---|---|---|
| 實際步驟 | 教程 | 操作指南 |
| 理論知識 | 說明 | 參考 |
鑑於這些重疊，不同類型的文檔變得混淆並相互混合也就不足爲奇了。雖然很難找到完全使用這四種結構的示例，但是大量的文檔都在努力以不同的方式來完成這四個類別的任務。有些項目就完全採用了這種結構，包括Django（雖然在早期版本中沒有明確說明）和django CMS。這兩個項目中都證明了這種結構的價值。
爲什麼要如此分析
本文的文檔結構分析基於我多年編寫和維護文檔的經驗並花了很多時間考慮如何改進它。它還基於各種學科的合理整合，例如，教程概念具有教學基礎；而且它假定存在一個老師和一個學習者，並把使用軟件作爲一種「手藝」來看待。
使你的文檔更有用
文檔維護人員必須解決的最大問題是沒有清楚瞭解他們應該做什麼，以至於他們改了又改但發現還是很難令人滿意。本文討論的文檔結構通過明確的分工來解決這些問題，基於此製作的文檔也更易於編寫和維護，同時也更易於使用。
應該寫什麼，怎麼寫，以及把它放在哪裏都變得更加清晰。
總的來說，針對四象限中的每一個文檔進行明確的編寫有助於軟件吸引和留住更多用戶同時用戶可以更高效地使用，這是軟件開發者最想要的東西之一。