原文來自 What nobody tells you about documentation，本文是本人整理翻譯而成。
關於如何寫好一個完善的軟件文檔，這裏應當是有四要素，而不是一個。它們分別是：教程，操作指南，說明和技術參考。它們代表四種不同的目的和功能，並且需要四種不同的方法來創建它們。瞭解這一點的含義有助於改進大多數的軟件文檔-通常會有非常好的效果。
前言
軟件有多好並不重要，因爲如果文檔不夠好，人們就不會使用它。
即使由於某種原因他們不得不使用它，這是因爲他們沒有選擇，沒有良好的文檔，他們將不會有效地使用它或者你喜歡它的方式。幾乎每個人都明白這一點。 幾乎每個人都知道他們需要良好的文檔，並且大多數人都試圖創建好的文檔。但大多數人都失敗了。通常這不是因爲他們不夠努力，而是因爲他們沒有找到正確的方式。
在本文中，我將解釋如何使您的文檔更好，而不是通過更加努力，而是通過正確的方式。 正確的方法是更簡單的方法 - 更容易編寫，更容易維護。
有一些非常簡單的原則可以管理少見的有拼寫的文檔。 它們似乎是一個祕密，儘管它們不應該是。如果您能夠將這些原則付諸實踐，它將使您的文檔更好，您的項目，產品或團隊更成功 - 這是一個承諾。
文檔需要包含並圍繞其四個不同的功能進行構建：教程，操作指南，說明和技術參考。 他們每個都需要一種獨特的寫作模式。 使用軟件的人在不同的環境中需要這四種不同的文檔 - 因此軟件中通常都需要它們。並且需要圍繞它們明確地構建文檔，並且它們必須保持獨立且彼此不同。
|
教程
|
操作指南
|
說明
|
技術參考
|
|
以學習爲導向
|
以目標爲導向
|
以理解爲導向
|
以信息爲導向
|
|
允許新人入門
|
展示瞭如何解決特定問題
|
解釋
|
描述軟件
|
|
是一個課程
|
是一系列步驟
|
提供背景和上下文
|
是準確且完整的
|
這種劃分使作者和讀者明白了哪些信息在哪裏。 它告訴作者如何編寫，編寫什麼以及在何處編寫它。 它使作者免於浪費大量時間來嘗試將他們想要傳達的信息篡改成有意義的形狀，因爲這些文檔中的每一種只有一個工作。
事實上，維護良好的文檔非常難以隱含或明確地識別該方案的象限。 每種類型的要求都與其他要求不同，因此任何未能保持這種結構的文檔嘗試都會受到影響，因爲它會立即被拉向不同的方向。
一旦理解了結構，它就成爲一種非常有用的工具，用於分析現有文檔，並瞭解需要採取哪些措施來改進它。
關於項目文件您可能會問：更改日誌，貢獻策略以及有關項目的其他信息在哪些方面適合此方案？ 答案是他們沒有 - 因爲嚴格來說，他們是項目文檔，而不是軟件本身的文檔，
它們可以簡單地與其他材料一起保存在適當命名的部分中 - 只要它們沒有混合在一起。
考慮到這一點，讓我們探討四個關鍵功能中的每一個。
教程
教程是讓讀者通過一系列步驟來完成某種項目的課程。 它們是您的項目所需要的，以向初學者展示他們可以用它實現某些目標。
他們完全以學習爲導向，具體而言，他們的目標是學習如何而不是學習。
你是老師，你負責學生的工作。 在您的指導下，學生將執行一系列操作以達到目的。
結束和行動取決於你，但決定他們應該做什麼可能是艱苦的工作。 最終必須有意義，但對於一個完整的初學者也是可以實現的。
考慮一個教孩子做飯的比喻。
你教孩子做飯的內容並不重要。 重要的是，孩子覺得它很有樂趣，並且有信心，並希望再次這樣做。
通過孩子所做的事情，它將學習烹飪的重要事項。 它將瞭解在廚房裏使用餐具來處理食物是什麼感覺。
這是因爲使用像烹飪這樣的軟件是一個技巧問題。 它是知識 - 但它是實踐知識，而不是理論知識。 當我們學習新工藝或技能時，我們總是開始學習它。
重要的是，完成教程後，學習者就能夠理解其餘的文檔和軟件本身。
大多數軟件項目都有非常糟糕或不存在的教程。 教程將使您的學習者變成用戶。 錯誤或缺少的教程將阻止您的項目獲取新用戶。
好的教程很難寫。 它們需要對初學者有用，易於遵循，有意義且極其健壯。
允許用戶學習
一開始，我們只是通過做才學到任何東西 - 這就是我們學會說話或走路的方式。
在您的軟件教程中，您的學習者需要做的事情。 在學習本教程時，他們所做的不同事情需要涵蓋廣泛的工具和操作，從最簡單的工具和操作開始，再到更復雜的工具和操作。
讓用戶開始
如果你的初學者的第一步是手持嬰兒步驟，這是完全可以接受的。 如果初學者要做的不是有經驗的人的方式，或者即使它不是“正確的”方式，那也是完全可以接受的 - 初學者的教程與最佳實踐的手冊不同。
教程的目的是讓學習者開始他們的旅程，而不是讓他們到達最終目的地。
請確認您的教程工作
作爲導師，你的一個工作就是激發初學者的信心：在軟件，教程，導師中，當然，還有他們自己實現所要求的能力。
有很多事情可以促成這一點。 友好的語氣和語言的一致使用以及材料的邏輯進展都有所幫助。 但最重要的是，你要求初學者做的事必須奏效。 學習者需要看到你要求他們採取的行動會產生你說他們會有的效果。
如果學習者的動作產生錯誤或意外結果，那麼您的教程就會失敗 - 即使這不是您的錯。 當你的學生和你在一起時，你可以拯救他們; 如果他們自己閱讀你的文檔你就不能 - 所以你必須提前防止這種情況發生。 毫無疑問，這說起來容易做起來難。
確保用戶立即獲得結果
學習者所做的一切都應該是可以理解的，無論多麼小。 如果你的學生在看到結果之前必須做兩頁的奇怪和難以理解的事情，那就太長了。 每一個行動的效果應儘快顯現和明顯，並且應明確與行動的聯繫。
教程的每個部分或整個教程的結論必須是有意義的成就。
使教程可重複
您的教程必須可靠地重複。 這不容易實現：人們將使用不同的操作系統，經驗和工具水平來實現它。 更重要的是，他們使用的任何軟件或資源很可能在此期間發生變化。
每次教程都必須適用於所有這些教程。
不幸的是，教程需要定期和詳細的測試，以確保它們仍然有效。
關注具體步驟，而非抽象概念
教程需要具體，圍繞特定的，特定的行動和結果。
引入抽象的誘惑是巨大的;畢竟大多數計算是如何獲得它的力量的。但是所有的學習都是從特定的，具體的到一般的和抽象的，並且要求學習者在他們甚至有機會掌握具體內容之前欣賞抽象層次是教學不好。
提供最低限度的必要解釋
不要解釋學習者爲了完成教程而不需要知道的任何內容。擴展討論很重要 - 只是不在教程中。在教程中，這是一個障礙和分心。只有最低限度是合適的。相反，請鏈接到文檔中其他地方的解釋。
只關注用戶需要採取的步驟
您的教程需要專注於手頭的任務。也許您引入的命令有許多其他選項，或者可能有不同的方法來訪問某個API。沒關係：現在，你的學習者不需要了解那些才能取得進步。
操作指南
操作指南使讀者瞭解解決實際問題所需的步驟。
它們是食譜，實現特定目標的方向 - 例如：如何創建Web表單; 如何繪製三維數據集; 如何啓用LDAP身份驗證。
他們完全以目標爲導向。
如果你想要一個比喻，想想一個食譜，準備吃東西。
配方有明確的定義結束。 它解決了一個具體問題。 它表明某人 - 可以假設他已經擁有一些基本知識 - 如何實現某些目標。
操作指南與教程完全不同。 操作指南是對真正的初學者甚至無法制定的問題的回答。
在操作指南中，您可以假設一些知識和理解。 您可以假設用戶已經知道如何執行基本操作並使用基本工具。
提供一系列步驟
操作指南必須包含需要按順序執行的步驟列表（就像教程一樣）。你不必從一開始就開始，只是在一個合理的起點。操作指南應該可靠，但它們不需要具有教程的鑄鐵可重複性。
關注結果
操作指南必須注重實現實際目標。別的什麼都是分心。與教程一樣，詳細說明在這裏不合適。
解決問題
操作指南必須解決特定的問題或問題：我如何...？
這是操作指南與教程不同的一種方式：當涉及到操作指南時，可以假定讀者知道他們應該實現什麼，但還不知道如何 - 而在本教程中，您有責任決定讀者需要了解的內容。
不要解釋概念
操作指南不應該解釋事情。這不是那種討論的地方;他們只會妨礙行動。如果解釋很重要，請鏈接到它們。
允許一些靈活性
操作指南應該允許稍微不同的方式來做同樣的事情。它需要足夠的靈活性，用戶可以看到它將如何應用於與您描述的示例略有不同的示例，或者瞭解如何使其適應與您假設的略有不同的系統或配置。除非你想到的確切目的，否則不要那麼具體，指南對任何事情都沒用。
隨時離開
實際可用性比完整性更有價值。教程需要完整，端到端的指南;操作指南沒有。它們可以在適合您的地方開始和結束。他們不需要提及所有要提及的內容，只是因爲它與主題相關。臃腫的操作指南無法幫助用戶快速獲得解決方案。
標題對用戶友好
操作方法文檔的標題應該告訴用戶確切的內容。如何創建基於類的視圖是一個很好的標題。創建基於類的視圖或更糟糕的是，基於類的視圖不是。
技術參考
技術參考是機器的技術說明以及如何操作。
技術參考只有一個工作：描述。它們是由代碼決定的，因爲它們最終描述的是：關鍵類，函數，API等等，它們應該列出函數，字段，屬性和方法等內容，並列出如何使用它們。
參考資料是面向信息的。
通過各種方式技術參考可以包含示例來說明用法，但它不應該嘗試解釋基本概念，或者如何實現共同任務。
參考資料應該是嚴格的，切中要害的。
烹飪類比可能是一篇關於一種成分的環球文章，描述了它的來源，它的行爲，它的化學成分，它是如何烹飪的。
請注意，描述確實包括如何使用機器的基本描述 - 如何實例化特定類，或調用某個方法，或者在將某些東西傳遞給函數時必須採取的預防措施。然而，這僅僅是其作爲技術參考的功能的一部分，並且強調不要與操作指南相混淆 - 描述軟件的正確使用（技術參考）與顯示如何使用它來實現某一目的不同（方法文檔）。
對於一些開發人員，參考指南是他們可以想象的唯一文檔。他們已經瞭解他們的軟件，他們知道如何使用它。他們可以想象其他人可能需要的是關於它的技術信息。
參考材料往往寫得很好。它甚至可以在某種程度上自動生成，但這本身就不夠了。
構建代碼周圍的文檔
爲參考文檔提供與代碼庫相同的結構，以便用戶可以同時導航代碼和文檔。這也將有助於維護人員查看缺少參考文檔或需要更新的位置。
始終如一
在技術參考中，結構，音調，格式必須一致 - 與百科全書或字典一致。
不要做任何描述
技術參考的唯一工作是儘可能清楚和完整地描述。其他任何事情（解釋，討論，指導，推測，意見）不僅會分散注意力，而且會使其更難以使用和維護。提供示例以在適當時說明說明。
避免使用參考材料來指導如何實現事物，超出使用軟件的基本範圍，並且不允許對主題的概念或討論進行解釋。相反，請酌情鏈接到操作指南，說明和教程。
準確性
這些描述必須準確並保持最新狀態。機器與您對它的描述之間的任何差異都將不可避免地導致用戶誤入歧途。
說明
說明或討論，闡明和闡明特定主題。它們拓寬了文檔對主題的覆蓋範圍。
他們是理解導向的。
說明同樣可以描述爲討論。它們是文檔放鬆和退回軟件的機會，從更廣泛的視角，從更高層次甚至從不同角度闡明它。您可以想象一個討論文檔是在閒暇時閱讀，而不是在代碼上閱讀。
這部分文檔很少明確創建，相反，解釋的片段分散在其他部分中。有時，該部分存在，但有一個名稱，如背景或其他筆記，並沒有真正公正的功能。
討論不像看起來那麼容易創建 - 當你有一個問題的起點時，直接解釋的東西就不那麼容易了，當你有一個空白頁面並且必須寫下一些關於它的東西時。
主題不是由您想要實現的特定任務定義的，例如操作指南，或者您希望用戶學習的內容，例如教程。它不是由一塊機器定義的，比如參考材料。它是由您認爲一次嘗試覆蓋的合理區域定義的，因此討論主題的劃分有時可能有點武斷。
提供上下文
說明是背景和上下文的位置 - 例如，Web表單以及如何在Django或Search和django CMS中處理它們。
他們還可以說明爲什麼事情如此 - 設計決策，歷史原因，技術限制。
討論替代方案和意見
說明可以考慮替代方案，或同一問題的多種不同方法。例如，在關於Django部署的文章中，考慮和評估不同的Web服務器選項是合適的，
討論甚至可以考慮並權衡相反的意見 - 例如，測試模塊是否應該在包目錄中。
請勿指導或提供技術參考
說明應該做的事情是文檔的其他部分沒有的。指示用戶如何做某事並不是解釋的地方。它也不應該提供技術描述。文檔的這些功能已在其他部分中處理。