用途
这套规范用于写技术文档，目标是让疲惫的工程师读第一遍就能理解。它把写作要求拆成四层，要求同时套用。资料给出的使用范围包括文档，也明确把 PR 描述和提交信息视为写作，除 Diátaxis 之外的所有层都适用于它们。
三层之上的原则
规范先提出三条高于分层规则的原则：
- 删掉不承担作用的词。 一个词去掉后句子仍成立，就去掉它。“in order to”写成“to”，“It is important to note that”则什么都不留。
- 使用短的日常词。 用“use”而非“utilize”，用“help”而非“facilitate”，用“do”而非“perform”。长词必须用精确性来换取它的长度。
- 当规则让句子变差时，换一种写法或干脆不改。 一个遵守了所有规则却读起来像机器写的句子，是失败的。
此外，代码库就是词表：要写真实的符号、文件、参数或命令名，而不是它的同义词或描述。不要发明行话，用开发者会开口说出的词，例如“move”“delete”“a budget that only decreases”，而不是“evacuate”“ratchet”“endgame”。某个命名模式如果在文档中首次出现时说明了含义，则可以使用。
节奏与具体性
文档可能遵守了每一层规则却仍读起来像机器写的：每句都很短、没有观点、没有具体内容。规范要求：故意混合句长，短句用来落一个观点，长句用来承载一个带有条件或结果的事实；一句一个想法不等于每句同一长度，承载两个想法的句子要拆开，承载一个想法的长句要保留。在模式允许的地方要有观点：解释类文档要权衡取舍并说出自己的判断，参考类文档则保持干燥。要具体而非无菌化：不写“schema changes can cause issues”，而写“a column rename fails the build”。
第一层：先选模式（Diátaxis）
一份文档只对应一个模式。用两个问题来选：内容是为行动服务还是为理解服务，以及为学习服务还是为工作服务。
- 行动 + 学习：教程（tutorial）。
- 行动 + 工作：操作指南（how-to）。
- 理解 + 工作：参考（reference）。
- 理解 + 学习：解释（explanation）。
这个罗盘可以用于整份文档，也可以用于一个句子。资料对四种模式分别给出了要求：
教程：在做的过程中学习。学习者的成功是你的责任，不是他们的。开头说明学习者将构建什么，而不是他们将“学到”什么。每一步都产生可见结果，且要早、要频繁。告诉他们应该看到什么：预期输出、提示符变化、日志行。解释压缩到一个从句加一个链接。保持具体，用“we”和命令式写作：先做 x，再做 y。
操作指南：通向目标的步骤。解决一个人有的问题，而不是机器能执行的操作。假定读者有能力，不做教学。只有行动：不跑题、不讲背景、不为完整性而完整，这些改用链接。允许分叉与判断：“If you want x, do y.” 用任务给指南命名，写“How to calibrate the radar array”，不写“Radar array calibration”。
参考：供查阅的事实。只做描述，不指导、不劝说、不带观点。干燥、完整、确定。陈述事实、选项、限制和错误，不做对冲。结构应镜像被描述之物的结构，使代码与文档可以对照浏览，把材料放在读者预期的地方，尽可能从代码生成。
解释：理解与原因。一个边界清晰的主题，脱离产品也能读。每个标题前都能容忍加一个隐含的“About...”。围绕一个真实的“为什么”问题展开。提供背景：设计决策、历史、约束、替代方案。只有在这里才允许观点。
不要把模式混在一起：教程里不放参考表格，参考里不放教程式手把手，操作指南里不辩论。应该拆分并链接。
第二层：面向读者的句子（Google 开发者风格）
用“you”和现在时与读者对话。“will”只用于确实在之后发生的事。说清谁做什么，写“the compiler checks”，不写“is checked”；被动语态只在施动者未知或不重要时使用。指令写成命令：“Click Submit.” 陈述事实要平实，绝不写“should be done”。条件放在指令之前：“To delete the document, click Delete.” 常见情况在前，例外在后。语气像一个懂行的朋友：不用流行词、不用比喻，指令中不用“please”，过程中绝不写“simply”“easy”“quickly”——如果这件事简单，读者就不会在这里。不要预告，比如“we will soon support...”，也不要连续用同一短语开头。链接词要说明去向：用页面标题或简短描述，绝不写“click here”；优先在本页给一句上下文，而不是链出去。
标题要承载观点而不只是话题，写“Pick the mode first”而不是“Modes”，使用句首大写。任务类标题是光杆动词短语，如“Create an instance”；概念类标题是名词短语。每页一个 h1，不跳级。序列用编号列表，其余用项目符号。列表前用完整句引导，列表项保持平行。代码用代码字体，UI 元素用粗体。使用序列逗号。去掉“etc.”，并在开头说明列表是不完整的。
第三层：让信息一次只承载一条（STE 规则）
每条指令一个句子，其他地方也是一句一个想法。约 20 词以上的指令、约 25 词以上的其他句子要拆分。把警告或条件放在它所保护的步骤之前：“If hot oil touches your skin, injuries can occur.” 保留“the”和“a”，因为“Remove backup file”有两种读法，“Remove the backup file”只有一种。给每个词一个含义和一项职责并保持一致：如果“check”表示检查，就不要又用它表示约束。每个动作固定一个词：这里用“start”，那里不要换成“initiate”。过程写成直接命令，绝不写成叙述，也不用被动：写“Install the component”，不写“the component must be installed”。尽量避免“-ing”形式。
第四层：消除两种读法（Global English）
把“only”“not”这类词紧挨着它们修饰的词：“only fails on growth”与“fails only on growth”含义不同。拆开长名词串：“the proto import budget check script”改为“the script that checks the proto-import budget”。让每个“it”“they”“this”都指向唯一明显的事物，存疑时重复名词，绝不用“this”或“which”指代整个从句。不要省略动词：“Phase 1 moves the converters and Phase 2 the runtime”让第二阶段丢了动词，要补上。保留显示结构的小词，例如“Ensure that the switch is off”中的“that”，绝不用词数换清晰度。系列中重复冠词以避免误读：当它们是两个东西时写“the client and the host”，不写“the client and host”。当句子可能有两种分组方式时，说明“and”或“or”连接的是哪些部分，“Both...and”“either...or”“if...then”是免费的消歧工具。用句号不用分号，用新句子代替破折号。括号内的文字要么是完整语法单位，要么是独立句子。绝不用“(s)”构成复数。不用斜杠，写“a, b, or both”而不写“a/b”或“and/or”。同一个事物在全文只用一个名字：一份文档里把同一个东西叫“the gate”“the ratchet”“the budget check”，等于教了三样东西；没有变化的部分不要翻来覆去改。避免习语、口语、拉丁缩写和隐喻。
仓库相关事项
规范要求对它涉及的每份文档应用 unslop 技能，该技能掌管 AI 词汇、填充、对冲、格式痕迹等口水话模式目录。资料的回应规则中提出，如果要新增冒犯词及其替换词，应作为对 unslop 的 abstract-metaphor 规则的补充，并附上 diff，但不要编辑那个技能。
PR 描述和提交信息也是写作，除 Diátaxis 外的每一层都适用。PR 正文是一份审阅者能在一分钟内读完的简报，不要粘贴 swarm 日志、SHA 列表或指标表格，改为给链接。产品 UI 文案不属于文档，应按产品自己的文案指南处理。代码片段用制表符缩进，写真实路径。每一个计数或目录树声明都必须在其落地的提交上为真，并附上可重新生成它的命令。
示例
原文："Configuration of the proto import ratchet budget script parameters is performed via budget.json. Note that it's important to remember that running with --write, which updates the committed budget to reflect the current count, should only be done when lowering it. If exceeded, CI fails."
改写："budget.mjs reads the committed budget from budget.json and counts the files that import protos. If the count exceeds the budget, CI fails. Run budget.mjs --write only to lower the budget."
限制与未提供信息
资料未提供该规范的安装命令、运行方式、平台要求、价格或收费信息，也未给出作者、许可证或版本信息，这些内容暂未提供。