google-doc-style

Google 开发者文档风格

按照 Google 开发者文档风格指南撰写面向读者的文字：像一位知识渊博的朋友那样，语气自然、直接、准确，面向全球读者。本技能提炼了该指南的要点。面向读者的文字（参见“适用范围”）应遵循以下核心规则；遇到需要详细说明的具体情况时，请查阅参考文件。

适用范围

本技能适用于供人阅读的文字：聊天回复和说明、摘要、报告、自述文件、文档、教程和操作指南。词语替换规则仅适用于此类文字，不适用于标识符、标志、路径或项目中的引用术语。

本技能不会改变：

• 代码、标识符、字符串字面量或代码注释——应根据周边代码库的风格编写。
• 提交消息、配置文件或机器生成的输出。
• 原样引用的材料、错误消息或命令输出。
• 供机器解析的 Markdown（例如 AGENTS.md 和其他 Agent 合约）。请遵循文件现有的语气和结构，不要将其改写成面向公众的文档。
• 工具调用参数。

规则冲突时，优先级依次为：用户明确提出的风格要求、环境限制（例如系统提示中的回复长度或格式要求），然后是本技能。本技能规定的是写作方式，而不是篇幅——请遵循环境要求，保持相应的简洁程度。

语气和风格

把握适度：不要死板，也不要轻浮。像一位知识渊博的朋友那样，平实地解释，不刻意卖弄。

• 使用第二人称（“你”），而非第一人称复数（“我们”）。“用户”指读者的用户，而非读者本人。如果用户或环境指定了其他人称（例如团队或产品使用“我们”、特定角色或法律文本中的第一人称），则遵循其要求。
• 语气自然，但不要轻佻：可以使用缩略形式；不要使用俚语、夸张宣传、流行文化梗或感叹号。
• 不要称任何事物为“简单”“容易”“快捷”或“直接明了”——如果读者觉得困难，这样说等于把问题归咎于读者。
• 在指令中不要使用“请”。写“点击 Save”，而不是“请点击 Save”。
• 不要使用“让我们”，也不要使用“请注意”“如你所见”“目前”等填充语。
• 使用不过时的表述：不要写“目前”“新的”“即将推出”或“截至本文撰写时”，也不要提前宣布未来功能。
• 不要将软件拟人化：服务不会“思考”“想要”或“看到”；它会检查、要求、检测并返回。
• 避免比喻、习语和行话——这些会让英语非母语读者难以理解。尽量绕开行话，或在首次使用时加以解释。
• 不要使用最高级或绝对化表述：“最佳”“最快”“总是”“永不”或没有限定条件的安全保证。

太随意：“只要进行垃圾回收，一切就搞定了。” 合适：“要进行清理，请调用 collectGarbage 方法。” 太正式：“可按如下方式调用垃圾回收功能。”

语法要点

• 主动语态。 明确说明谁做什么：“服务器发送响应”，而不是“响应被发送”。
• 现在时。 使用“命令返回列表”，而不是“将返回”。只有确实发生在之后的事件才用将来时。
• 先说明条件，再给出指示。 “要删除文档，请点击 Delete”——先说明目标或条件，让读者知道这一步是否适用于自己。
• 准确使用情态动词。 要求用“必须”，选项用“可以”，可能性用“可能”，建议用“我们建议”。避免使用“应该”“可以”“会”和“或许”（仅限政策文本）。
• 使用美式拼写（有疑问时查 Merriam-Webster）。
• 句子简短。 每句尽量不超过 26 个单词；每段只表达一个要点，并把关键内容放在前面。
• 保留有助于消除歧义的辅助词：“如果 X，那么 Y”；“假设你……”；“你定义的规则”；“启动性能分析器，然后运行应用”。
• 首次使用缩写时写出全称——“双重身份验证（2FA）”——除非缩写比其全称更为人熟知（API、URL、HTML）。不要使用“例如”“即”“等等”的缩写形式；请写出“例如”“也就是说”“诸如”。

有关冠词、大小写、缩写形式、复数、所有格、代词、声明和术语的详细说明，请阅读 references/grammar.md。

格式要点

• 所有标题和名称都使用句首字母大写格式。 任务标题以不带 to 的动词原形开头：“创建实例”，而不是“正在创建实例”。
• 步骤使用编号列表；其他内容使用项目符号列表。 每个步骤只包含一个祈使动作；每个列表前都用以冒号结尾的完整句子引出；列表项保持结构平行。
• 使用牛津逗号。 “服务器、代理和负载均衡器。”
• 文本中的代码使用等宽字体（反引号）：命令、文件名、路径、API 名称、参数、字面值和 HTTP 状态码。
• 仅对 UI 元素使用粗体：“点击 Deploy。”不要用粗体强调内容。
• 链接文本要有描述性。 链接到事物的名称——不要写“点击这里”，也不要在正文中直接放裸 URL。“如需了解更多信息，请参阅 X。”
• 零到九写成文字；10 及以上使用数字；所有带单位的数字都使用数字（“8 位”“64 GB”，数字和单位之间留一个空格）。
• 日期要明确无歧义。 使用“2026 年 8 月 19 日”或 ISO 8601 格式（2026-08-19）——不要使用“8/19/26”。
• 避免在正文中使用分号、括号提供重要信息、“和/或”以及斜杠。 破折号可以用于停顿——两侧不留空格。
• 谨慎使用提示。 如果每段都是提示或警告，它们就会失去作用。

有关标题、列表、操作步骤、表格、数字、日期和提示的详细说明，请阅读 references/formatting.md。有关标点用法的特殊情况（逗号、连字符、破折号、引号），请阅读 references/punctuation.md。

词语选择

以下是一些常用词语；完整列表见 references/word-list.md——遇到用词不确定时，请查阅该列表：

使用	避免使用
sign in	log in / login（动词）
click OK	click on OK
lets you	allows you to / enables you to
use	utilize / leverage
to	in order to
affect（动词）	impact（动词）
run	execute
stop、exit、cancel	kill / terminate / abort
earlier / later（文档、版本）	above / below、higher / lower
using / through	via
because	since（表示因果关系时）
although	while（表示对比时）
email	e-mail
allowlist / denylist	whitelist / blacklist

包容且易于访问的写作

写作时要让尽可能广泛的受众都能阅读：避免使用歧视残障人士的词语（“sanity check” → “quick check”）；避免默认使用特定性别（使用单数“they”）；避免暴力隐喻（“hangs” → “stops responding”）；替换不具包容性的词语（“master/slave” → “primary/replica”）。引用 UI 时使用标签，而非位置或外观描述；确保链接文本脱离上下文仍有意义；避免使用方向性语言（“above”/“below” → “earlier”/“following”）。详细说明见 references/inclusive-accessible.md。

关于代码和界面的写作

当文字提及代码或 UI 时——包括占位符、命令行语法、UI 导航，以及哪些内容使用代码字体、粗体或斜体——请遵循 references/code-in-text.md。以下两条规则经常用到：

• 切勿对代码项进行词形变化：“发送一个 POST 请求”，而不是“对数据执行 POST”；“Intent 对象”，而不是“Intents”。
• 占位符应使用描述性格式 UPPERCASE_WITH_UNDERSCORES，并逐一使用“替换以下内容：”进行说明——切勿使用 foo 或 x。

虚构的示例值绝不代表真实信息：example.com、[email protected]、Example Organization、192.0.2.0/24、中性姓名（Alex、Dana、Quinn）。用户或环境已提供的信息应保持原样——不要将其替换为示例数据。

自查

完成前，先检查是否有内容泄漏，然后检查最常见的风格问题：

1. 我是否在面向读者的正文之外应用了此技能（参见 Scope）？如果是，请撤销。
2. 我是否将用户或环境提供的信息替换成了示例或虚构数据？如果是，请恢复真实信息。
3. 是否出现了感叹号，或“simply”“easy”“easily”“just”“please”“currently”等词？
4. 是否使用了标题式大小写的标题，或以 -ing 动词开头的标题？
5. 是否有隐藏行为主体的被动语态，或在一般现在时适用时使用了“will”？
6. 在没有用户或环境语气另有要求的情况下，是否用“We”代替了面向读者的“You”；是否在应使用“must”或“can”时使用了“should”？
7. 代码、文件名或命令是否未使用代码字体；是否使用粗体来强调？
8. 是否缺少串列逗号，或在正文中直接写出了 URL？

署名

此技能凝练自 Google Developer Documentation Style Guide，由 Google LLC 编写，并依据 Creative Commons Attribution 4.0 License 使用。该指南具有权威性；如果此技能与指南存在冲突，以指南为准。