technical-documentation

技术文档

像 Google 的技术写作者那样审核、编写并改进开发者文档：从读者的任务出发，对照代码核实每项事实，然后按严重程度顺序应用风格指南——先调整结构，再调整语气，最后斟酌用词。

核心原则

**围绕读者的任务写作，而非罗列产品功能。**Google 的指南要求文风亲切而不轻浮、准确且一致，因为阅读文档的开发者是为了完成任务，而不是欣赏产品。指南中的两条原则决定了以下所有内容：

• **指南，而非规则。**如果偏离指南能改善内容，就可以灵活处理——应优先采用已确立的领域术语——但要确保文档内部一致。
• **优先顺序。**首先遵循项目自己的风格指南，然后依次遵循 Google 的指南、Merriam-Webster（拼写）、《芝加哥格式手册》（通用风格）和 Microsoft Writing Style Guide（技术风格）。

规则分为两层。结构和内容规则（标题、操作步骤、代码示例、第二人称、主动语态、历久弥新的文档、无障碍性）适用于任何语言的文档。标有 [EN] 的规则（拼写、系列逗号、缩写、词汇表）仅适用于英文文本——其他语言的文档可跳过这些规则，且除非有人提出要求，否则绝不翻译文档。

评分

目标：10/10。分数 = 通过的快速诊断项数（共 10 项，每项 1 分；非英文文档自动通过 [EN] 项）。等级：9-10 = 可直接发布；7-8 = 只需修改措辞和语气；5-6 = 先重组章节，再重新编辑；≤4 = 按文档类型的框架重写。阻断性问题——错误或无法核实的事实、无法完成的操作步骤、仅存在于图片中的信息或缺少替代文本的图片——需单独处理：无论分数如何，修复之前文档都不得发布。报告分数、未通过的项目，以及达到 10/10 所需的具体修改。

框架

1. 了解读者和文档的用途

**核心概念：**每个页面都服务于一位读者，帮助其完成一项任务。动笔前先明确读者和任务——受众及其水平，以及读者读完后能够完成什么——并选择合适的文档类型：教程（通过实践学习）、操作指南（完成任务）、概念文档（理解原理）、参考文档（查找信息）、README（了解项目并开始使用）。

**为何有效：**读者会快速浏览以寻找所需内容；如果一个页面混杂概念、操作步骤和参考信息，读者就不得不通读全文才能找到需要的内容。

要点：

• Google 的 Technical Writing 课程要求在文档开头说明受众、范围和非范围——非范围声明可以帮助不该阅读此页面的读者及时找到正确页面
• “开始之前”部分应在第 1 步之前列出前提条件，而不是把它们放进第 4 步（惯例）
• 先讲要点：引言应说明读者将获得什么，而不是介绍产品的历史
• 每个操作类页面都应以验证步骤（“确认……”）和“后续步骤”结尾（惯例）

应用场景：

场景	应用方式	示例
README	帮助读者了解项目：说明它是什么、适用对象、三步上手流程，以及相关链接	用途 → 安装 → 首次运行 → 文档导航
混合页面	将概念和操作步骤拆分到相互链接的页面中	“OAuth 的工作原理” + “配置 OAuth”
教程与操作指南	教程从头到尾讲解一条完整路径；操作指南则假设读者已了解相关背景	“构建你的第一个插件”与“添加一个钩子”

选择文档类型或重组文档时，请参阅 references/document-types.md，其中包含 README、入门指南、教程、操作指南和概念文档的框架、受众和范围声明，以及适用于大型文档集的自我编辑流程。

2. 语气：以你为主语、主动语态、现在时、历久弥新

核心概念： 用“你”称呼读者，让每个句子的动作主体明确，用现在时描述行为，并假设读者会在五年后阅读此页面。

关键要点：

• “我们”会隐藏动作主体；“用户”则把读者变成第三方——两者都会削弱指引的效果
• 只有在动作主体未知或无关时才使用被动语态（“文件在静态存储时会加密”）
• 只有确实会在之后发生的效果才用“将”：写“服务器会发送确认”，而不是“将发送”
• 可以使用缩写形式——Google 在表达否定时更偏好用“isn't”而不是“is not” [EN]
• 软件不会想、看或思考：写“API 会检测”，而不是“API 会看到”
• 不要使用“please”（仅在征求许可时使用）、“simply / easily / just”或最高级——如果某个步骤很简单，读者会自己发现
• 保持历久弥新：删掉“currently”“new”和“soon”；绝不要提前宣布尚未发布的功能

修改前 → 修改后：

• “请注意，用户登录后，新仪表板将简单地显示出来。” → “登录后，仪表板会显示。”
• “我们建议由客户端刷新令牌。” → “从客户端刷新令牌。”

如果文档的语气不合适或前后不一致，请参阅 references/voice-and-words.md，了解语气规则及指南中的准确例外、包容且面向全球读者的措辞，以及完整的用词列表。

3. 句子和用词

核心概念： 先说明条件，再给出指令；每个句子只表达一个意思；优先选择指南用词列表推荐的浅白词语。

关键要点：

• “要删除文档，请点击 Delete”——读者会在操作前判断步骤是否适用，而不是操作后才判断
• 首次使用缩写时，先写出全称，再在括号中注明缩写；普遍熟知的缩写（URL、HTML）除外
• 拉丁语缩写不易翻译，也不便于快速浏览：写“例如”，不要写“e.g.”；写“也就是说”，不要写“i.e.”；省略“etc.”或写完整个列表 [EN]
• “can”表示能力，“may”表示许可，“might”表示可能性 [EN]
• 用词列表示例 [EN]：sign in（不要用 log in）· set up 作动词 · lets you（不要用 allows you to）· through 或 by using（不要用 via）· after（不要用 once）· use（不要用 leverage 或 utilize）· checkbox · email
• 对目标读者来说可以接受的术语，对其他人来说可能就是缺陷——请加以定义或添加链接

修改前 → 修改后：

• “完成后，也就是所有字段都填写完毕后，点击 Save 以保存设置。” → “填写完所有字段后，点击 Save。”
• “CLI 利用 GCP SDK（例如用于身份验证）。” → “CLI 使用 Google Cloud SDK，例如用于身份验证。”

审核用词选择时，请参阅 references/voice-and-words.md，了解用词列表表格（避免使用 → 建议使用 → 原因）、缩写规则和情态动词。

4. 结构：标题、列表、表格、提示

**核心概念：**结构是读者的导航图。使用句首字母大写格式的标题就像目录；列表承载由完整句子引出的平行条目；表格要有标题行；提示应少用且言之有物。

关键要点：

• 任务标题使用简洁的祈使句（“创建实例”）；概念标题使用名词短语（“实例生命周期”）；标题不要以“-ing”形式结尾
• 列表需要以冒号结尾的引导句，且所有条目都采用相同的语法形式；仅在顺序重要时使用编号
• 对于成对数据，描述列表（术语 → 定义）优于两列表格
• 表格：要有标题行和引导句，不能合并单元格或留空单元格——屏幕阅读器依赖这些内容
• Note = 有用但可选；Caution = 谨慎操作；Warning = 可能造成伤害或不可逆的数据丢失。不要堆叠使用；实际操作中，每个部分最多使用一个（推断）
• 交叉引用使用“参见”，绝不使用“上方”或“下方”——页面会重新排版，也会被翻译
• 链接文字应说明目标（“参见配置自定义域名”），绝不使用“点击此处”
• 替代文本应说明图片的用途；重要信息绝不能只放在图片中

应用场景：

场景	应用	示例
文字密集的页面	每当任务发生变化时，插入一个任务标题	“安装”、“配置”、“验证”
连续三个提示	将其中两个合并到正文中；保留会改变操作方式的那个	一个关于数据丢失的 Caution
选项表格	标题行 + 引导句 + 表格单元格措辞保持平行	“以下标志控制输出：”

修正页面结构时，请参见 references/structure-and-formatting.md——其中包含标题、列表、表格、提示、交叉引用、链接文字、图片、数字和日期规则，以及前后对照示例。

5. 操作步骤与代码

**核心概念：**操作步骤是一个编号列表，每一步只包含一个祈使操作，并说明操作位置和预期结果。代码使用代码字体，并由以冒号结尾的句子引出；占位符必须让读者一眼就能看出它不是字面值。

关键要点：

• 每步只执行一个操作；可选步骤使用“可选：”前缀；只有一步时使用项目符号，不要写“1.”
• 子步骤使用 a、b、c；记录最短路径，不要列出所有替代方案
• UI 元素名称使用粗体，并与屏幕上的大小写一致；鼠标操作用 click，触屏操作用 tap，不依赖设备时用 select
• 文件名、路径、命令、标志、参数和值使用代码字体——产品名称除外
• 占位符使用 ALL_CAPS_WITH_UNDERSCORES，不要使用 <your-key> 或 YOUR_API_KEY，并在示例后立即说明（“将 PROJECT_ID 替换为……”）
• 命令语法：[optional] 表示可选项，{a|b} 表示互斥选项，... 表示可重复参数
• 示例必须可运行、简洁、每行不超过 80 个字符，并展示预期输出

修改前 → 修改后：

• “使用密钥运行以下命令：shipit deploy --key=<your-key>” → “要进行部署，请运行以下命令：” → 围栏代码块中的 shipit deploy --key=API_KEY → “将 API_KEY 替换为 Settings 页面中的密钥。”
• “1. 现在你应该点击 Deploy 按钮来进行部署。” → “1. 点击 Deploy。状态将变为 Deploying。”

编写操作步骤或示例时，请参见 references/procedures-and-code.md——其中包含完整的操作步骤规则、UI 元素与设备操作动词、正文中的代码、占位符、命令行语法，以及示例代码质量检查清单。

6. 参考文档：API、文档字符串、CLI 帮助

核心概念： 参考文档的文字有意采用描述性、完整且程式化的写法——读者会查阅这些内容，因此每个条目都必须存在，且写法保持一致。

关键要点：

• 为每个公共类、方法、字段、常量和枚举值编写文档；缺少条目会让人以为该功能“不受支持”
• 方法描述以表示类别的动词开头：“获取……”“设置……”“检查是否……”“创建……”“返回……”——切勿写成“此方法……”
• 非布尔参数以“The…”或“A…”开头；布尔参数应写成“If true, … If false, …”（动作）或“True if …; false otherwise”（状态）
• 为每个有返回值或异常的方法编写返回值和异常说明（“在……时抛出”）
• 弃用元素应在第一句话中指出替代项
• CLI --help（惯例——Google 没有 --help 页面）：用法行采用 [optional] 语法，包含单行摘要，并以统一的占位符样式描述每个标志

修改前 → 修改后：

• “此方法用于获取客户。” → “获取指定 customerId 对应的客户。不存在该客户时会抛出 NotFoundError。”
• “@param force - 强制标志” → “@param force 如果为 true，即使存储桶中包含对象也会将其删除。如果为 false，当存储桶非空时操作会失败。”

编写或审核参考文档时，请参阅 references/api-reference.md——其中包含按类别划分的动词表、参数、返回值和异常的写法、一份完整的 JSDoc 示例，以及 CLI 帮助惯例。

7. 发行说明、变更日志、迁移指南

核心概念： 变更日志是为即将升级的读者编写的文档。每条内容都应说明变更内容、对读者的影响以及需要采取的操作——结构遵循 Keep a Changelog，语气与其余文档一致。

关键要点：

• 最新版本列在最前面，顶部设有 Unreleased 部分，版本标题使用 ISO 日期，并链接到差异（Keep a Changelog）
• 将条目归入 Added / Changed / Deprecated / Removed / Fixed / Security；切勿直接粘贴提交消息
• 破坏性变更放在该版本的最前面，并附上迁移步骤链接（惯例）
• 弃用条目应指出替代项以及移除版本或日期
• 迁移指南应采用操作流程的形式：“开始之前”（版本、备份）、带有修改前后代码片段的编号步骤、“验证迁移”、回滚
• 对每条内容应用 Google 风格：操作说明使用第二人称，不使用“当前/新的”，标志和 API 使用代码字体，并始终保持时态一致

修改前 → 修改后：

• “身份验证模块有各种改进（#412）” → “Changed：login() 现在返回 Session，而非令牌字符串。请更新读取 .token 的调用方——参阅 迁移到会话。”

编写发行说明或迁移指南时，请参阅 references/release-notes.md——其中包含 Keep a Changelog 的基本结构、各类别条目的写法、弃用措辞，以及迁移指南的操作流程。

8. 运行审查、改写或撰写

核心概念： 三种模式，一套准则：接收需求 → 遵循本地规范 → 站在读者角度阅读 → 核实事实 → 按严重程度应用规则 → 按固定格式输出。

流程：

1. 接收需求。 确认模式（审查、改进或撰写）、文档类型、读者及其水平，以及语言。对于撰写，必须明确读者的任务和事实来源（代码路径、现有文档）——缺少这些信息时不要开始。
2. 本地风格指南。 查找 CONTRIBUTING.md、STYLE.md、docs/style-guide.md、.vale.ini，以及现有文档遵循的惯例（例如，全文统一使用“log in”）。这些优先于 Google。如果项目需要使用代码检查工具，Vale 配合 Google 套件可以自动检查 [EN] 单词和标点这一层。
3. 在进行任何审查或改进之前，阅读 references/audit-checklist.md——审查结果中引用的规则 ID 都在其中；切勿引用尚未读过的 ID。
4. 先站在目标读者的角度通读文档，再对照代码检查每条命令、标志、参数和行为，然后评判文风。文风出色但内容错误的文档，比文风糟糕但内容正确的文档更糟。
5. 按严重程度顺序应用规则： 阻断级 → 高级（结构、无障碍、缺少参考条目）→ 中级（语态、提示、引言句）→ 低级（词汇表、标点 [EN]）。
6. 输出。 问题的位置必须方便读者查找：使用标题路径，审查文件时还要注明行号。改进 = 一行 Score before → after、完整的改写后文档，然后是 ## Change log 表格（Change | Rule ID + name | Why）。事实保持不变——源文档中陈述的事实视为用户提供的信息，因此应保留（如果没有代码证据确认，则标注 TODO(verify): …），而不是删除。撰写 = 文档，对每处信息缺失都标注 TODO(verify)。切勿加入代码中未出现且用户未提供的命令、标志或参数。

审查时始终按以下格式输出：

# Documentation Audit: [path or title]
**Score:** X/10 — [band]   **Shippable:** yes | no (blocking findings below)
**Diagnostic:** N/10 — failed rows: [row numbers + one-line reason each]
**Doc type / reader:** [type] for [audience, level]   **Language:** [en | xx — [EN] rules skipped]
**Local style guide:** [file found and honored | none — Google applies]
**Blocking:** [wrong/unverifiable facts, unfollowable steps, image-only information — or "none"]
**Findings:**
| # | Location | Rule (ID + name) | Before | After | Severity |
**Rewrite plan:** [ordered: structure → voice → words; what to do first to reach 10/10]

运行任何审查或改写时，请参阅 references/audit-checklist.md——其中包含完整的规则表及 ID 和严重程度、严重程度判定标准、非英语内容处理方式、Vale 配置，以及一份完整的迷你审查示例。

常见错误

错误	失败原因	修正方法
按功能而非读者任务组织内容	读者需要在多个章节间查找同一个工作流	明确读者的任务；选择文档类型；每页只介绍一项任务
核实事实之前先修正文风	润色过的错误说明会更久地受到信任	先对照代码检查每条命令和参数
使用“点击此处”和“见下文”	脱离上下文、供屏幕阅读器阅读或页面重新排版后，这些表述都毫无意义	链接文本应说明目标；交叉引用使用“参见”
将步骤埋在段落中，使用被动语态和将来时	读者无法判断由谁执行操作，也不知道操作顺序	使用编号的祈使句步骤，先写条件，使用现在时
连续堆叠 Note/Warning 提示框	处处大声疾呼，反而无人留意	每个章节只保留一条提示；其他内容改为正文
使用 <your-key> 或 YOUR_API_KEY 占位符	读者可能会输入尖括号，或把前缀当作字面内容	使用大写的 API_KEY，并在示例后加以说明
以“修正文风”为由改写含义	审阅者认可了文字，发布的却是错误行为	保持事实不变；将未知内容标注为 TODO(verify)

快速诊断

问题	如果否	操作
第一段是否说明了文档面向谁，以及读者将能够做什么？	读者无法判断这是不是自己要找的页面	补充受众、预期结果和范围之外的内容
文档类型是否符合读者的任务（教程 · 操作指南 · 概念 · 参考 · README）？	概念和步骤交织在一起；读者找不到所需内容	按类型拆分页面；在页面之间添加链接
每条命令、标志、参数和行为是否都已根据代码或用户核实？	文档教了错误的内容	核实或标记为 TODO(verify)；修复前不得发布
标题是否构成句子式目录（任务标题用祈使句，概念标题用名词短语）？	扫读效果不佳；以“-ing”结尾的标题掩盖了操作	重写标题；在每项新任务开始处添加标题
所有流程是否都采用编号步骤，每步只包含一项祈使操作，并将条件放在前面？	读者会漏掉步骤，或在检查前就采取行动	将段落改为步骤；将条件前移
每个代码示例前是否都有以冒号结尾的介绍句，并解释了 ALL_CAPS 占位符？	读者会粘贴字面值，或不知道示例的作用	添加介绍句；修正并解释占位符
文本是否采用第二人称、主动语态和现在时，且不使用 please/simply/just，也不拟人化？	说明读起来像是在讲故事	逐句重写；删去赘词
链接是否具有描述性，交叉引用是否使用“请参阅”式表达，图片是否有替代文本，表格是否有表头？	屏幕阅读器和页面重排会出问题	逐项修正；将仅以图片呈现的信息移入文本
内容是否经得起时间推移——不含“目前/新/即将推出”等表述，也不预告功能？	文档一发布就会过时	删除时间相关词语；只描述已发布的行为
[EN] 是否遵循词表、系列逗号、缩写和美式拼写规范，或本地指南？	细微的不一致会削弱信任	遵循词表；如已配置则运行 Vale

关于来源

Google 开发者文档风格指南是 Google 技术写作者为 developers.google.com、Android 和 Google Cloud 文档维护的公开写作规范；配套的 Technical Writing One 和 Two 课程是 Google 面向工程师的内部培训课程，现已公开发布。本技能依据 CC BY 4.0（遵循 Google 网站政策）对两者进行了改编，并为发行说明加入了 Keep a Changelog；这是独立改编版本，未经 Google 认可。

延伸阅读

• Google 开发者文档风格指南 — 从 要点 和 词表 开始
• Technical Writing One 和 Technical Writing Two — Google 关于词语、句子、文档、自我编辑和代码示例的课程
• Keep a Changelog — 本技能用于发行说明的变更日志结构
• "Docs for Developers: An Engineer's Field Guide to Technical Writing"，作者：Jared Bhatti、Zachary Sarah Corleissen、Jen Lambourne、David Nunez 和 Heidi Waterhouse
• "Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web"，作者：Mark Baker