你需要了解的几种技术文档类型

我见过太多团队把技术文档等同于API参考手册，恨不得把所有方法、参数、返回值塞进一个页面，然后丢给开发者自己消化。结果呢？开发者要么对着密密麻麻的代码发懵，要么直接放弃集成。说实话，技术文档的价值不在于罗列了多少接口，而在于能不能帮用户快速搞懂、上手、甚至爱上你的产品。Baklib 在服务客户时，我们经常强调：好的技术文档应该像一本产品使用说明书，既有菜谱（代码示例），又有攻略（主题指南），还有百科（参考指南），甚至需要一个社区来补全那些官方文档没空管的小众场景。这就是我所谓的产品内容体验——从用户视角出发，把文档变成产品体验的一部分。

89% 的开发者在工作中会用到 API，技术文档的分量不言而喻。但仅仅列出一份 API 参考已经不够了——想让你的 API 成功，就需要创建更多文档来解释它的方方面面。

在本文中，我们将探讨如何全面地记录 API，并了解不同类型的技术文档。你会看到，文档完善的 API 不仅能让用户更轻松，还能让软件对新客户更具吸引力。

我们先从技术文档的标配说起：代码示例。

你几乎找不到一份不带代码示例的技术文档。这种最常见的文档类型让开发者可以试用 API 并观察效果，是企业展示软件解决方案的绝佳机会。

如果你对代码示例的贡献还有疑问，不妨把它们看作是菜谱。像菜谱一样，代码示例更像是指南而非刻板的规则。你可以随意调整、增加、删除和修改元素，调试代码以最好地满足自己的需求。

连开发者都接受了这个比喻，并经常用它来描述代码样例。例如，某个仓库的作者用食物名称来标识库中的每一个 React hook。

记住，Julia Child 不会介意你在菜谱里多加一撮盐，API 的作者们也绝不会介意用户调整代码来最大化利用 API。

但是，想让开发者用你的代码，就必须让它易于获取。这就是为什么大多数技术文档都提供可直接复制粘贴的代码。

Shopify 的技术文档更进了一步——在每个代码示例中加入了一个方便的复制按钮，缩短了本已很快的复制粘贴流程。

Shopify 能成为代码示例的典范还有一个原因：作者为每个代码示例写了清晰的说明，解释了它的功能。

无论文档多么直观，人们总有办法误解它，导致不太理想的结果。但像这样清晰的说明可以确保开发者把你的示例变成成功的 API。

因此，除了列出代码的“配料”，你还要确保 API 示例附带有信息丰富的解释——这才是完整的 API“菜谱”。

有时，零散的代码片段无法充分展现产品的价值。为了展示 API 的全部潜力，你可以创建一份主题指南——也就是技术文档的另一种类型。

在这一节，我们将用 Stream 公司（生产聊天和活动流 API 的公司）的文档为例，分析深度主题指南。

简单的概述和 API 导览是吸引潜在客户的好方式。例如，Stream 提供了一个模拟解决方案实现的 API 导览。所有代码都在那里，你只需点击按钮，就能亲眼看到产品成形。

不过，如果你想让用户深入了解 API，就需要覆盖它的专业领域。面向有技术背景的读者撰写的主题指南，能够展现 API 背后的思路和概念设计。

这种类型的技术文档虽然需要更多时间创建，却能说服高级客户相信 API 的质量。

Stream 的主题指南先是介绍了与产品核心元素——动态流组织相关的关键概念。

普通的开发者其实不一定需要完全理解这些概念才能成功实现解决方案，但像这样的概述有助于勾勒出整体解决方案的图景。

同样，你可以用深度主题指南来展示软件的设计和架构，就像 Stream 做的那样。

通过阅读文档的其余部分，用户可以了解更多 API 的细节。

总而言之，深度主题指南或许不是最直截了当的 API 呈现方式，但它毫无疑问是提升技术文档质量的宝贵资产。它可以让你围绕 API 构建叙事，展示其背后所有的精妙之处，证明你已经严谨地覆盖了 API 的方方面面。

参考指南是最直截了当的技术文档类型。它们剖析 API，列出了使用它所需的所有信息，比如方法、类、函数等的详细信息。

API 参考通常结构一致，因此相对容易编纂。参考指南中常见的元素包括：

实际效果可参考 Square 的 API 参考指南。正如你所见，Customers API 被分成了客户档案相关的几部分，从列出客户到添加群组成员。每个端点都以简短描述开头，并附有一个代码示例。你还可以查看查询参数和响应字段信息。

尽管参考指南包含使用 API 所需的关键数据，但你不应该只依赖参考来介绍你的 API。正如 ReadMe 的创始人 Gregory Koberger 所说：“你不会扔给某人一本同义词词典就指望他学会英语；同样，你也不应该扔给某人参考指南就指望他学会使用你的 API。”

总结一下：如果你想为用户提供清晰的 API 概览，当然应该创建参考指南，但不要忘记用其他文档类型来补充，让 API 更容易理解。

如果我们告诉你，你可以部分外包你的技术文档，并用真实用户的宝贵输入来丰富它，你会怎么想？没错，支持论坛是一种很好的技术文档类型，它让你能够覆盖所有边界情况，又不会把主要文档弄乱。

如果你把 API 的每一种可能的场景都描述出来，文档会变得难以阅读，用户可能因此放弃产品。这时支持论坛就派上用场了。

这些数字空间让你能够解决用户遇到的问题，并让这些知识公开可用。我们来看一个 Unity 支持论坛的问题，它在发布多年后依然很有帮助。

Unity 的官方文档没有涵盖 SceneView 类的 API，所以用户到社区求助。Unity 可能认为 API 的某个特定方面不够重要，不值得纳入官方文档，但其他论坛用户提供了自制解决方案。

除了依赖社区，一些公司也鼓励支持人员回答论坛问题。无论哪种方式，这种非结构化内容都能让你覆盖不常见的场景，同时保持正式文档的简洁。

如果想延长支持论坛的使用寿命，应该让知识库可以被搜索。这样就能避免大量重复的提问，为用户提供经过验证的解决方案。

看看三年后一位感激的 Unity 用户对刚才那个 SceneView 回答的评价：

所以，当官方文档没有空间展开 API 的某个方面时，支持论坛可以填补缺口。支持论坛的另一个好处是能减少收到的工单数量，降低运营成本。遇到问题的用户可以先查论坛，发现解决方案已经在上面了。

毕竟，90% 的客户在遇到支持问题时希望得到即时回复，一个支持论坛可以让你在用户心中保持良好的形象。

不过，为了取得最佳效果，请记住论坛的公开性质。审核内容可以确保社区成员提供的答案相关且有用。你可以通过定期检查内容、标记错误或不恰当的回复、验证最佳答案来改善用户体验。

既然你已经为创建优质技术文档付出了那么多努力，不把这些文档用于推广就太可惜了。你可以用 API 营销材料来补充文档。

这些涵盖了为推广 API 而制作的各类内容，例如教程、新闻稿、信息图，甚至社交媒体帖子。打磨 API 参考和代码示例当然是向开发者保证产品质量的好方法。

一份像 Notion 那样整理得井井有条的参考指南，难道不能让人们对公司充满信心吗？

如果你为 API 撰写好的文档，你已经领先于许多竞争对手。许多公司错误地认为技术文档是开发周期的最后一步，生产出一份杂乱无章的文档。

然而，正如我们在这篇文章中所展示的，技术文档远不止参考指南。它包括多种类型，每一类都在帮助用户和推广 API 方面发挥着作用。

把你所有的 API 文档都想象成一顿饭：代码示例是食谱，主题指南是完整的菜单卡，参考指南是食材列表，支持论坛是就餐用户的评论。而营销材料则是餐馆的广告。

你的 API 文档越完整，用户就越容易看到它的价值。通过用正确的材料来支持 API，你就能成功地在开发者社区中推广它。

用 Baklib 来搭建你的技术文档中心吧，它可以帮助你轻松地创建、管理和发布各种类型的技术文档。

---

Baklib数字内容体验云是一个综合性的云平台，旨在通过云原生的形式为企业提供中台式全栈数字内容的管理。它结合了媒体资源管理、知识库、网站管理、知识社区、数据分析和AI就绪等技术，以支持创建、管理、发布和优化数字内容。Baklib专注对数字内容的最大化利用，帮助企业在各种数字渠道上提供一致性、相关性且吸引人的数字体验。