什么是软件文档？ 入门的类型和最佳实践

如果您希望开发人员和最终用户从您的软件中获得尽可能多的价值，您需要创建高质量的软件文档。

但是什么是真正的软件文档，您如何才能为您的项目创建它呢？

在这篇文章中，我们将深入探讨您需要了解的有关软件文档的所有信息，包括以下内容：

• 什么是软件文档？
• 不同类型的软件文档（附示例）
• 如何发布你的软件文档（最好的工具）
• 创建高质量软件文档的一些最佳实践

让我们开始吧！

什么是软件文档？

软件文档是帮助最终用户、开发人员和/或您的员工了解您的软件并使用它有效地实现他们的目标的内容。

通常，您会在您的网站上发布软件文档。 然后人们可以访问它以了解有关您的软件及其工作原理的更多信息。

在软件文档的广泛定义中，有不同类型的软件文档。 让我们接下来讨论。

不同类型的软件文档

您可以将不同类型的软件文档大致分为几大类。

首先要考虑的是文档适用于哪种类型的人：

• 用户文档——这是您为产品的最终用户创建的文档。 它可以帮助他们从普通用户的角度了解如何使用您的软件，普通用户可能拥有也可能没有任何特殊技术知识。
• 开发人员文档——这是您为开发人员创建的更具技术性的软件文档，例如 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。

您将获得自托管平台的灵活性和所有权，以及发布高质量软件文档所需的所有特性和功能。

如果您想了解更多，请单击此处转到英雄知识库。