技术文档检查清单

技术文档的目标读者是开发人员，他们需要一边了解技术文档，一边学会如何在实际工作中使用它。因此，一份真正有价值的技术文档必须同时包含描述性内容和实操代码。

这份清单涵盖了这两类要素，以及一些实用的优化和分享技巧。通过勾选清单中的部分或大部分项目，你将拥有一份完善的技术知识库，开发人员会乐于反复查阅。

我们从最基础的部分开始。

在技术文档的开头加入总体概述部分总是个好主意，确保每篇文章都包含这一节。

我们见过很多文档直接切入代码，不愿用介绍和概述“浪费”用户时间。但这可能适得其反。

用户很可能因为缺乏引导而花费大量时间在错误的文档中摸索。为了避免这种令人沮丧的情况，尽量在文档开头提供清晰的总体概述。

以 Stripe 为例：Stripe 的文档总是以一段简短介绍开头，精确说明文档所涉及的操作、对象或资源的作用。这段文字告诉读者文档的主题，以及跟随指南后能达成什么目标。读完这一节，用户就知道这是否是他们要找的信息，还是需要继续搜索。写这一节只需几分钟，但对用户极其有用，所以确保每份文档顶部都有总体概述。

每项活动都有起点或开始方式，使用技术文档也不例外。为了向用户展示技术文档的工作原理，你需要以“快速入门”指南的形式提供第一步。

以 GraphQL 的 API 指南为例：快速介绍之后，紧接着解释如何安装或启动产品/功能/操作。用户可以通过复制并运行一段代码来启动一个 GraphQL 服务器。指南随后列出用户成功安装和使用产品所需的其他步骤。

提供这种快速启动选项能让用户快速沉浸到技术文档中，并保持参与感——因为他们不仅仅是阅读文档，还在同步使用产品。简而言之，提供快速入门指南能让文档更具互动性，用户更愿意继续阅读，从而成功使用你的技术方案。

除了概述和入门指南，技术文档还应包含开发者基础要素。这些是技术文档的基本运行参数，必须详细描述才能正确无误地使用。以下是可能需要包含的要素：

包含这些要素能让文档成为开发人员的宝贵参考，帮助他们更高效地工作。例如，当开发人员遇到错误时，他们可以在文档中查找错误码，了解原因。如果文档足够详尽，还会提供可能的原因和最短时间内修复错误的步骤。记住，技术文档的核心是为用户提供实用工具和可操作建议，让你的技术方案使用起来得心应手。

诚然，开发人员更喜欢直接看代码并自己尝试，所以技术文档是一种文本不多、更多依赖代码来传达信息的文档类型。但技术文档的使用者仍然是真实的人，因此除了代码，还需要提供文本形式的指导。因此，在检查文档时，别忘了确认参数、端点、调用和身份验证方法等都有详细描述。

以身份验证为例：有多种方式验证请求，因此必须非常具体地解释你的方法。例如，GitHub 对其 REST API 的身份验证基础提供了非常详细的说明。

至于其他元素，如参数，不要害怕重复。即使是非常相似的调用，每次都需要提供完整描述，因为用户不会通读整份文档，而只会阅读他们感兴趣的具体文章。总之，你的技术文档在每篇文章都配有恰当描述之前，还不能发布。

现在来到最有趣的部分——至少对开发者用户来说是如此。代码示例向开发者展示如何完成不同任务并应对各种场景。因此，只要有可能，就应该提供代码示例，尤其是在引导用户完成复杂工作流程的文档中。Twilio 的研究表明，代码示例出现得越早，用户在页面上的停留时间越长。Shopify 的技术文档就很好地践行了这一原则：文档中充满代码示例，让开发者几乎能在技术文档范围内做任何事，比如检索客户信息。更重要的是，代码示例应能让用户直接复制粘贴到自己的应用中。如果你使用 Baklib 这样的优质文档工具，输入代码并使其可复制将变得非常容易。代码示例让技术文档具有交互性和可操作性，所以在引导用户时别忘了尽可能多地包含它们。

既然提到示例，值得注意：开发者在使用技术文档时几乎可以使用任何编程语言来发起请求。这意味着你应该尽量提供多种编程语言的示例。这样，你的文档就能帮助尽可能多的开发者。例如，MailChimp 的技术文档提供了五种语言的代码示例，用户可自由选择语言。

---

Baklib 是业界首创的客户支持知识库系统和领先的数字体验平台。它通过统一的工作流程为整个客户在线支持生命周期提供支持。Baklib 是全球领先的数字体验平台，拥有涵盖内容、实验和商业的可组合技术套件。