跳转到主要内容
好的技术文档只有一个目标：帮助用户完成任务并回到工作中。风格和语气的选择要么支持这个目标，要么成为障碍。清晰一致的写作能建立用户信任。不一致或含糊的写作会制造摩擦，削弱用户对产品的信心。 本指南涵盖了有效技术写作背后的核心原则，并提供如何应用这些原则的实用指导。

​
使用第二人称

直接以”你”来称呼用户。第二人称使说明更容易理解，并将重点放在用户正在做什么，而不是产品做了什么。 
<!-- 第二人称（推荐） -->
你可以在设置文件中配置超时时间。

<!-- 第三人称（避免） -->
用户可以在设置文件中配置超时时间。
第二人称还有助于发现被动语态：当你写”你”时，你不得不说明是谁在做什么。

​
使用主动语态

主动语态使句子更短、更清晰。在被动语态中，主语接受动作。在主动语态中，主语执行动作。 
<!-- 主动 -->
当 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 都是免费且广泛使用的。
使用 workflow 按计划运行风格审核，或在每次向文档仓库推送更改时运行。

​
常见问题

根据受众和产品背景调整正式程度。面向工程师的开发者工具可以直接简洁——跳过客套直接进入代码。面向技术水平较低的用户或企业产品的文档通常受益于更温暖的语气，能预见用户的困惑。无论哪种情况，都要避免僵硬的企业语言。“利用”并不比”使用”更精确。像一个知识渊博的同事解释事情那样写作，而不是像法律文件那样描述。
当执行者未知、不相关，或当强调结果比强调谁造成的更重要时。“请求在处理前会被验证”如果你是在描述请求发生了什么而不是谁验证了它，这是没问题的。当被动语态掩盖了用户需要执行的操作的责任人时，它就成了问题。
确定每个页面的主要受众并为他们写作。入门指南应假设最少的先验知识。API 参考应假设读者知道 API 是如何工作的。错误在于试图在同一页面上服务两者——在参考页面上添加初学者上下文会拖慢专家的速度，而在教程中假设专家知识会让初学者迷失。如果你确实有两个不同的受众，请考虑为每个受众创建不同的内容类型。请参阅内容类型获取指导。
维护一个术语列表——一个简单的首选术语和应避免术语的表格。与所有文档贡献者共享，并在审查时检查。Vale 可以通过自定义词汇文件自动执行。维护列表的投入很快就能通过减少审查周期和减少用户对混乱术语的投诉来获得回报。
足够长以完整覆盖主题，足够短以保持聚焦。如果一个页面涵盖两个不同的任务，考虑将其拆分。如果它涵盖一个任务但内容单薄，可能缺少重要细节。参考内容可以长而密集——用户会浏览它。概念内容应该更短——用户会阅读它。请参阅内容类型了解更多关于如何根据内容目的调整页面长度的信息。

内容类型

为你的文档目标选择合适的内容类型。

无障碍访问

让你的文档对更多用户无障碍可用。

文本格式

了解文本格式和样式选项。

SEO 最佳实践

提高文档的可发现性。