如何撰写技术文档

好的技术文档只有一个目标：帮助用户完成任务并回到工作中。风格和语气的选择要么支持这个目标，要么成为障碍。清晰一致的写作能建立用户信任。不一致或含糊的写作会制造摩擦，削弱用户对产品的信心。

本指南涵盖了有效技术写作背后的核心原则，并提供如何应用这些原则的实用指导。

直接以”你”来称呼用户。第二人称使说明更容易理解，并将重点放在用户正在做什么，而不是产品做了什么。

<!-- 第二人称（推荐） -->
你可以在设置文件中配置超时时间。

<!-- 第三人称（避免） -->
用户可以在设置文件中配置超时时间。

第二人称还有助于发现被动语态：当你写”你”时，你不得不说明是谁在做什么。

主动语态使句子更短、更清晰。在被动语态中，主语接受动作。在主动语态中，主语执行动作。

<!-- 主动 -->
当 token 过期时，API 会返回错误。

<!-- 被动 -->
当 token 过期时，会返回一个错误。

被动语态并非总是错误的。当执行者未知或不重要时，被动语态是合适的。但将被动语态作为默认习惯会使文档更难阅读。

一个快速测试：如果你能在动词后面加上”被僵尸”，那这个句子就是被动的。“一个错误被返回了[被僵尸]“是被动语态。“API 返回了[被僵尸]一个错误”是主动语态。

文档被浏览的次数远多于被阅读的次数。冗长的句子和密集的段落会在用户试图找到特定答案时拖慢他们的速度。

准则：

• 尽量将句子控制在 25 个词以内
• 每个句子只表达一个观点
• 每段两到四个句子
• 将步骤列表用编号序列分开，而不是连续的长段落

如果一个句子需要多个逗号或分号才能连贯，那它很可能可以拆分成两个句子。

标题为人类和搜索引擎组织页面。编写标题时应回答用户可能提出的问题，而不是从产品角度标注主题。

<!-- 面向意图（更好） -->
## 如何配置身份验证

<!-- 主题标签（较弱） -->
## 身份验证配置

所有标题使用句首大写（“入门指南”，而不是每个词都大写）。不要跳过标题层级——从 H2 到 H3，而不是从 H2 到 H4。

在 Mintlify 文档中，页面的 H1 会从 title: frontmatter 属性自动生成。不要在正文中手动添加 H1。

为每个概念选择一个术语并在所有地方使用。在”API key”、“API token”和”access token”之间来回切换来描述同一事物，会迫使用户停下来猜测你是否在说同一件事。

首次引入一个术语时，在当前位置直接定义它，而不是链接到其他页面。

<!-- 在上下文中定义 -->
每个请求都需要一个 API key——一个用于标识你账户的唯一 token。

<!-- 不要假设用户已有相关知识 -->
每个请求都需要一个 API key。

如果你的产品对事物有特定名称（对象、操作、UI 元素），请完全按照它们在产品中出现的方式使用这些名称。保持大小写一致。

语气应该与用户试图做的事情相匹配。面向新用户的入门指南适合更温暖、更鼓励的语气。面向经验丰富的开发者的 API 参考更适合密集和精确，而非温暖。

一些适用于所有内容类型的原则：

• 直接但不生硬。“点击保存”比”请在准备好继续时点击保存按钮”更好。
• 避免填充短语。“值得注意的是”、“为了”、“请注意”和”只需”增加了词汇量却没有增加含义。
• 不要发表评论。“这是一个强大的功能”是一种观点。记录它的功能，而不是它有多令人印象深刻。
• 使用用户的词汇。 如果你的用户称之为”webhook”，不要在文档中称之为”event callback”。使用他们已经在搜索的词。

团队会发展出用户从未接触过的简称。检查新内容中是否有对首次接触产品的人来说陌生的术语。

决定产品功能名称是否大写（“Dashboard”、“API Explorer”）并始终如一地应用。大小写不一致表明缺乏对细节的关注。

非正式短语和习语更难翻译，对非母语人士来说也更难理解。面向国际受众的文档应使用简单直接的语言。

即使只有少量错误也会降低可信度。它们表明没有人仔细审查过内容，这会让用户怀疑技术内容是否同样不可靠。

写作原则只有在成为可重复工作流的一部分时才能持续。以下是一些自动化执行的方法：

• Vale： 一个针对散文的 linter，可以根据可配置的风格规则进行检查。你可以编写规则来强制使用你自己的术语、标记被动语态或捕获常见错误。
• CI 检查： 在每个 pull request 上运行 Vale 或其他 linter，以便在内容合并之前发现风格问题。
• 现有风格指南： 与其从头编写规则，不如从已有的指南开始。Google Developer Documentation Style Guide、Microsoft Style Guide 和 Splunk Style Guide 都是免费且广泛使用的。