什麼是軟件文檔？ 入門的類型和最佳實踐

如果您希望開發人員和最終用戶從您的軟件中獲得盡可能多的價值，您需要創建高質量的軟件文檔。

但是什麼是真正的軟件文檔，您如何才能為您的項目創建它呢？

在這篇文章中，我們將深入探討您需要了解的有關軟件文檔的所有信息，包括以下內容：

• 什麼是軟件文檔？
• 不同類型的軟件文檔（附示例）
• 如何發布你的軟件文檔（最好的工具）
• 創建高質量軟件文檔的一些最佳實踐

讓我們開始吧！

什麼是軟件文檔？

軟件文檔是幫助最終用戶、開發人員和/或您的員工了解您的軟件並使用它有效地實現他們的目標的內容。

通常，您會在您的網站上發佈軟件文檔。 然後人們可以訪問它以了解有關您的軟件及其工作原理的更多信息。

在軟件文檔的廣泛定義中，有不同類型的軟件文檔。 讓我們接下來討論。

不同類型的軟件文檔

您可以將不同類型的軟件文檔大致分為幾大類。

首先要考慮的是文檔適用於哪種類型的人：

• 用戶文檔——這是您為產品的最終用戶創建的文檔。 它可以幫助他們從普通用戶的角度了解如何使用您的軟件，普通用戶可能擁有也可能沒有任何特殊技術知識。
• 開發人員文檔——這是您為開發人員創建的更具技術性的軟件文檔，例如 API 文檔。

第二個考慮因素是文檔是針對外部還是內部受眾：

• 外部軟件文檔——這是您為幫助用戶而創建的面向公眾的文檔。
• 內部軟件文檔——這是您為員工創建的私人文檔，旨在幫助他們更有效地工作並了解關鍵細節。

例如，您可能有一套開發人員文檔供內部團隊使用以幫助開發軟件，而另一套面向公眾的開發人員文檔供外部開發人員使用。

讓我們更詳細地分解這些類型的軟件文檔……

開發人員文檔的軟件文檔示例

• API 文檔——向開發人員展示如何與軟件的 API 交互。
• 自述文件——介紹您的軟件並解釋它的作用——通常是人們首先閱讀的內容。
• 發行說明——記錄軟件的新版本，包括任何重要的更改。
• 架構文檔——顯示軟件的結構，可能包括圖表。
• 數據模型文檔——記錄軟件中的不同數據結構，包括不同數據結構之間的關係。
• 流程文檔——記錄錯誤報告、路線圖、質量保證、測試協議等關鍵流程。

對於以開發人員為中心的文檔的真實軟件文檔示例，您可以查看 Gravity Forms 的“開發人員”文檔，其中涵蓋了各種主題，例如：

• PHP 鉤子（用於 WordPress）
• 數據對象
• PHP API
• 數據庫
• 休息API

例如，REST API 文檔如下所示：

用戶文檔的軟件文檔示例

• 入門指南——向用戶展示如何快速啟動和運行您的軟件。
• 特定用例的教程——用於完成特定任務的更具體的教程。
• 術語詞彙表/參考手冊——幫助用戶理解關鍵術語和細節。
• 常見問題——回答常見問題。

有關更多以用戶為中心的軟件文檔的真實示例，您可以轉向上面的相同 Gravity Forms 示例。

如果您查看 Gravity Forms 的更多以用戶為中心的文章，您會看到許多關於如何使用軟件界面完成任務的分步教程，以及關鍵功能的詞彙表和解釋。

與開發人員軟件文檔相比，您會看到更多的屏幕截圖和通俗易懂的語言解釋以及更少的代碼塊。

如何發佈軟件文檔：三種最佳軟件文檔工具

要在網站上發佈軟件文檔，您需要專用的軟件文檔工具或某種類型的知識管理系統。

在本節中，我們將快速介紹一些最好的軟件文檔工具。 然後，在下一節中，我們將討論創建高質量文檔的一些最佳實踐。

如果您想更深入地了解這裡，您可能需要閱讀我們關於最佳文檔工具和最佳技術文檔軟件的完整指南。

英雄知識庫

Heroic Knowledge Base 是流行的開源 WordPress 軟件的文檔和知識庫插件。

借助 Heroic Knowledge Base，您可以自行託管文檔並保持完全控制，同時仍然可以訪問創建有效軟件文檔所需的所有功能。

以下是 Heroic Knowledge Base 的一些核心功能：

• 靈活的內容編輯器，包括用於標註和其他重要樣式細節的內置塊。
• 自動目錄，以便用戶可以快速查看文檔文章中涵蓋的內容並跳轉到特定部分。
• 通過本機 WordPress 修訂系統進行修訂控制和版本歷史記錄。
• 內容髮現功能包括帶有實時建議、類別等的實時 Ajax 搜索。
• 用戶反饋系統，讓人們將文章評為有幫助或無幫助並分享反饋。
• 搜索分析，以便您可以查看用戶正在搜索的內容，以及任何返回零結果的搜索詞。
• 即時回答小部件，讓用戶可以從您站點的任何位置搜索和訪問軟件文檔。

因為 Heroic Knowledge Base 和 WordPress 都是自託管和開源的，所以您還可以根據需要自由修改您的設置。

您可以使用密碼、用戶帳戶、IP 地址、內部網等各種策略使其面向公眾或限制對文檔的訪問。

Heroic Knowledge Base 起價僅為每年 149 美元。

閱讀文檔

Read the Docs 是一個文檔工具，專注於幫助您創建開發人員文檔。

如果您特別專注於創建技術開發人員文檔，那麼它可能是另一個值得考慮的好選擇。

您可以使用 Git 管理您的內容和修訂歷史，然後將您的文檔部署到前端界面。

以下是閱讀文檔中的一些其他值得注意的功能：

• 內置分析功能可查看您的用戶正在閱讀和搜索的內容。
• 支持多個並發構建，如果您提供多個版本的軟件，這會很有幫助——例如，一套文檔用於 1.0 版，另一套用於 2.0 版。
• 導出不同格式的文檔，包括 PDF、HTML 和 epub。
• 幫助用戶查找文檔的實時搜索建議。

如果您有開源軟件項目，可以免費使用 Read the Docs。

對於商業軟件產品，有付費的 Read the Docs for Business 服務，起價為每月 50 美元。

GitBook

GitBook 是另一種技術軟件文檔工具，可讓您使用 Git 管理文檔，同時支持 GitHub 和 GitLab 存儲庫。

或者，如果您不想使用 Git，GitBook 還允許您使用文本編輯器創建文檔或從 markdown 或 .doc 文件導入文檔。

以下是 GitBook 提供的其他一些值得注意的功能：

• 版本控制以跟踪修訂和版本歷史記錄。
• 如果您需要讓多位作者協作撰寫文章，則實時團隊編輯會很有幫助。
• 使用“空間”和“集合”組織文章——每個空間可以有多個集合。
• PDF 導出選項使用戶可以輕鬆地將您的文檔導出為 PDF 下載。

GitBook 對非營利組織或開源項目免費。

對於商業軟件項目，GitBook 起價為每個用戶每月 8 美元，最少 5 個用戶。 這意味著最便宜的月費是每月 40 美元。

創建軟件文檔的最佳實踐

最後，讓我們深入研究一些軟件文檔最佳實踐，以幫助您創建有效的文檔。

考慮用戶的目標和需求

當您撰寫軟件文檔文章時，從回答幾個基本問題開始很重要：

• 您為誰編寫的用戶？
• 用戶想要完成什麼？
• 用戶的技術知識水平如何？

了解這些問題的答案將有助於您了解要涵蓋的內容以及如何以最佳方式構建文章。

例如，假設您提供社交媒體日程安排軟件，並且您正在撰寫一篇文章來幫助社交媒體經理安排他們的第一個社交媒體帖子。

在編寫軟件文檔時，您可能希望專注於為普通最終用戶展示實現該目標的最直接方法。

如果您還提供一個 API 讓開發人員設置他們自己的集成，您可能希望在另一篇文章中介紹它（儘管您可能會提到並鏈接到該方法）。

在開發過程中包含軟件文檔

當您創建軟件文檔時，很容易陷入等到項目完成後再記錄它的陷阱。

但是，這會很快導致文檔欠債，因為您可能會在新功能或更改被記錄之前發布它們。

為避免這種情況，讓軟件文檔成為軟件開發週期中有意識的一部分。 如果尚未記錄新功能或產品，即使代碼本身已完成，它也未準備好發布。

通過使文檔成為軟件開發過程的核心要求，您可以確保您交付的所有產品都附有適當的文檔。

使用一致的格式和样式

為了幫助人們更有效地使用您的軟件文檔，在所有文檔中使用一致的格式和样式非常重要。

使用相同的格式可以讓讀者了解您的軟件文檔的結構，這將使他們更容易快速訪問所需的信息。

為了幫助實現這種一致性，您可能需要創建專門的軟件文檔樣式指南。

您的軟件文檔管理工具可能還包括幫助您實現一致樣式的功能。

例如，Heroic Knowledge Base 插件包括預先設置樣式的標註以突出顯示關鍵信息或警告。 通過使用這些，您可以確保所有文檔的格式一致。

使用專家編寫技術文檔

對於面向用戶的軟件文檔，您可能不需要主題專家來編寫內容。

但是，對於技術性更強的軟件文檔，例如以開發人員為中心的 API 文檔，您可能希望指派具有相關技術知識的人來編寫這些文檔。

如果您的組織有資源聘請該職位，這可能是具有領域專業知識的敬業技術作家。 或者，它可能是您的開發人員之一。

重要的是作者對你的軟件的技術方面有足夠深的理解，可以向其他技術用戶解釋。

讓人們更容易發現內容（搜索/過濾）

隨著您的文檔庫的增長，用戶將越來越難以找到滿足他們需求的文檔文章。

為盡量避免此問題，您需要專注於提高軟件文檔的可發現性。

第一個策略是按類型劃分文檔。

例如，您通常希望將最終用戶文檔與開發人員軟件文檔分開。

其中，您還可以使用類別進一步劃分文章。 您可以使用基於功能、用例、附加組件等的類別——任何對您的軟件產品具有邏輯意義的類別。

與上面相同的 Gravity Forms 示例保持一致，您可以看到 Gravity Forms 按功能類型劃分其最終用戶文檔。

另一個有用的可發現性功能是實時搜索建議。 用戶可以開始在搜索框中鍵入相關查詢，並立即查看與該查詢匹配的文檔文章。

許多文檔工具包括內置的實時搜索功能，包括 Heroic Knowledge Base。

保持您的軟件文檔更新

因為您的軟件總是在變化，所以您的軟件文檔將永遠是一個正在進行的工作。

當您的軟件發生變化時，您需要及時更新您的文檔以反映這些變化。

否則，您的文檔不僅“沒有幫助”，而且實際上可能會給您的用戶造成混淆。

為確保進行這些更新，您需要指定特定人員負責文檔和更新流程。 這樣一來，誰負責保持一切準確就沒有歧義了。

使用客戶反饋來改進您的文檔

除了讓您自己的團隊審查和更新您的軟件文檔之外，您還需要考慮客戶反饋。

客戶可以提供有關某個軟件文檔文章有多大用處（或可能無用）的有價值信息，以及您可以如何改進它的詳細信息。

要使客戶反饋流程自動化，您需要尋找一種包含用於客戶反饋的內置功能的文檔管理工具。

例如，Heroic Knowledge Base 插件讓用戶可以將文章評為有幫助或無幫助，還可以選擇提供自由形式的反饋。

然後，您可以從儀表板查看所有這些信息，以快速發現需要改進的文檔文章。

立即開始為您的軟件編寫文檔

軟件文檔可幫助您和您的客戶更有效地工作並從您的軟件中獲得更多價值。

有不同類型的軟件文檔，因此您需要考慮哪些類型符合您的軟件項目的需要。

對於內部或外部團隊，以及不同類型的客戶（例如開發人員與最終用戶），您可能有不同的文檔。

要創建有效的文檔，您需要遵循本文中的最佳實踐。

要發布該文檔，您可以使用開源工具，例如基於功能強大的 WordPress 軟件的 Heroic Knowledge Base。

您將獲得自託管平台的靈活性和所有權，以及發布高質量軟件文檔所需的所有特性和功能。

如果您想了解更多，請單擊此處轉到英雄知識庫。