按 Google 技术写作规范审计…

当你需要审计、重写或从零撰写开发者文档（README、入门指南、教程、how-to、API 参考、docstring、CLI 帮助、变更日志、迁移指南）时，按读者任务与 Google 风格指南分层修正结构与措辞。

适用场景

解决思路

1. 先确定读者与文档类型：明确目标读者及其水平、读完后能做什么，并选择匹配的文档类型（tutorial 边做边学、how-to 完成任务、concept 理解概念、reference 查阅、README 定位与起步）。
2. 在开头写受众说明与范围/非范围声明，把前置条件放在步骤 1 之前的“Before you begin”，先讲关键要点（读者能得到什么），每个流程页结尾加验证步骤（“Confirm that…”）和“What's next”。
3. 把概念与操作拆分为互相链接的独立页面，避免同一页混合概念、步骤和参考内容。
4. 统一语气：用第二人称“you”，使用主动语态和现在时，让每句话的执行者明确；被动语态仅在执行者未知或无关时使用（如“The file is encrypted at rest”）。
5. 避免“will”描述当前行为（仅用于真正后续发生的事），避免“we”“the user”，避免拟人化（用“The API detects”而非“the API sees”），不用“please / simply / easily / just”和最高级形容词。
6. 保持文档“无时效”：删除“currently”“new”“soon”，不预告未发布功能。
7. 英文文档可用缩写（isn't 优于 is not），但非英文文档跳过所有 [EN] 规则，且未经要求不要翻译文档。
8. 句子层面：把条件放在指令之前（“To delete the document, click Delete”），一句一个意思；首次出现缩写时写全称并在括号中给出简写（URL、HTML 等通用缩写除外）。
9. 英文中避免拉丁缩写：用“for example”代替“e.g.”、“that is”代替“i.e.”，省略“etc.”或补全列表；区分 can（能力）、may（许可）、might（可能性）。
10. 按词表选词：sign in（非 log in）、set up 作动词、lets you（非 allows you to）、through 或 by using（非 via）、after（非 once）、use（非 leverage/utilize）、checkbox、email；术语对目标读者可用，对其他读者需定义或链接。
11. 结构层面：标题用句子式大小写，任务标题用祈使句（“Create an instance”），概念标题用名词短语（“Instance lifecycle”），不用“-ing”标题；任务变化处就加标题。
12. 列表需有以冒号结尾的引导句，各项语法形式一致，仅在有顺序时用编号；成对数据用描述列表（术语→定义）而非两列表格。
13. 表格要有表头行和引导句，不合并或留空单元格；交叉引用用“see”，不用“above/below”；链接文字要说明目标（“see Configure a custom domain”），不用“click here”。
14. 图片必须有替代文本说明用途，信息不能只存在于图片中；提示框慎用：Note 为可选有用信息、Caution 为需谨慎、Warning 为伤害或不可逆损失，每节最多一个。
15. 流程写作：用编号步骤，每步一个祈使动作，说明在哪操作和预期结果；可选步骤加“Optional:”前缀；单步用项目符号而非“1.”；子步骤用 a、b、c；只记录最短路径。
16. UI 元素名用粗体并与屏幕大小写一致；鼠标用 click、触屏用 tap、设备无关用 select；文件名、路径、命令、标志、参数和值用代码字体，产品名不用。
17. 占位符用 ALL_CAPS_WITH_UNDERSCORES（如 API_KEY），不用 <your-key> 或 YOUR_API_KEY，并在示例后立即解释（“Replace PROJECT_ID with…”）。
18. 命令行语法用 [optional]、{a|b} 表示互斥选项、... 表示可重复参数；示例应可运行、最小化、80 字符换行，并展示预期输出。
19. 参考文档：记录每个公开类、方法、字段、常量和枚举值；方法描述以类别动词开头（Gets/Sets/Checks whether/Creates/Returns），不用“This method…”。
20. 非布尔参数以“The…”或“A…”开头；布尔参数用“If true, … If false, …”（动作）或“True if …; false otherwise”（状态）；记录返回值和异常（“Thrown when…”）；弃用元素在首句说明替代品。
21. CLI --help 用 [optional] 语法写 usage 行、一行简介，每个标志用统一占位符风格描述。
22. 变更日志：最新版本在前，顶部保留 Unreleased 段，版本标题用 ISO 日期并链接到 diff；按 Added/Changed/Deprecated/Removed/Fixed/Security 分组，不粘贴 commit 信息。
23. 破坏性变更放在版本最前并链接迁移步骤；弃用条目说明替代品和移除版本或日期；迁移指南按流程写：Before you begin（版本、备份）、编号步骤含前后代码片段、Verify the migration、rollback。
24. 执行审计/改写/撰写时按协议：确认模式（audit/improve/write）、文档类型、读者与水平、语言；查找本地风格指南（CONTRIBUTING.md、STYLE.md、docs/style-guide.md、.vale.ini 及现有约定），本地指南优先于 Google。
25. 审计或改写前先读 references/audit-checklist.md，引用规则 ID 前必须已读过；先以目标读者身份冷读文档，再对照代码核查每条命令、标志、参数和行为，最后才评判风格。
26. 按严重度顺序应用规则：Blocking → High（结构、可访问性、缺失参考条目）→ Medium（语气、提示框、引导句）→ Low（词表、标点 [EN]）。
27. 输出格式：审计用固定模板（Score、Shippable、Diagnostic、Doc type/reader、Language、Local style guide、Blocking、Findings 表、Rewrite plan）；improve 输出一行 Score before → after、完整改写文档和 Change log 表（Change | Rule ID + name | Why）；write 输出文档并对每个缺口标 TODO(verify)。
28. 事实保持不变：源文档中的事实视为用户提供，保留而非删除，无代码佐证时标 TODO(verify)；绝不写入未在代码中见过或用户未提供的命令、标志或参数。

适用边界 · 注意事项

• 营销文案或落地页文案（应使用 storybrand-messaging）。
• 代码注释与命名规范（应使用 clean-code）。
• 非英文文档不要套用 [EN] 规则（拼写、连续逗号、缩写、词表），也不要未经要求翻译文档。