--- name: technical-writing description: "分层技术写作标准:Diátaxis 结构、Google 开发者风格句子、STE 指令规则、Global English 句法。用于 /technical-writing,或编写、审查文档、RFC、README、PR 描述或提交消息时。" disable-model-invocation: true --- # 技术写作 写到让疲惫的工程师第一次阅读就能理解。四层标准全部应用。 三条规则优先于各层: - **删掉每个没有作用的词。** 去掉某个词后句子仍成立,就删掉它。“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”。有名称的模式可以使用,但文档首次出现时应解释含义。在回复中附 diff,建议将新发现的不当词语及替代写法加入 `unslop` 的抽象隐喻规则。不要编辑该技能。 ## 变化节奏 文档可能遵守每层标准,读起来却仍像机器写的:每句话都被截得很短,到处没有观点,也没有具体内容。 - 有意混合句子长度。短句强调要点。长句承载事实及其条件或后果。 - 每句一个想法不意味着每句一样长。承载两个想法的句子要拆开。只承载一个想法的长句可以保留。 - 模式允许时表达观点。解释类写作要权衡取舍,因此说明你如何看待它们,而不只是罗列利弊。参考资料保持客观平实。 - 优先具体,避免空泛。不要说“schema changes can cause issues”,而应说“a column rename fails the build”,即“重命名列会导致构建失败”。 ## 先选择模式(Diátaxis) 一份文档,一种模式。用两个问题来选择:内容支持的是行动(做)还是理解(想)?它服务于学习还是工作? - 行动 + 学习:**教程**。 - 行动 + 工作:**操作指南**。 - 理解 + 工作:**参考资料**。 - 理解 + 学习:**解释**。 这套指向原则既可用于整份文档,也可用于一句话。 **教程:通过实践学习。** 学习者成功是你的责任,不是他们的。开头说明学习者会构建什么,而非会“学到”什么。每一步都产生可见结果,而且应尽早、频繁地产生。告诉他们应该看到什么:预期输出、提示符变化、日志行。解释缩减为一个分句和一个链接。保持具体。使用“我们”,采用命令式:“先做 x。现在做 y。” **操作指南:通往目标的步骤。** 解决一个人面临的问题,而非描述机器能执行的操作。假定读者有能力,不做教学。只写行动:不岔题、不铺背景,不为完整而完整。把这些内容改为链接。允许分支和判断:“如果你想要 x,就做 y。”用任务命名指南:“如何校准雷达阵列”,而不是“雷达阵列校准”。 **参考资料:供查阅的事实。** 只描述。不指导、不说服、不表达意见。保持平实、完整、确定。陈述事实、选项、限制和错误,不用模糊措辞。结构应对应被描述对象,使代码和文档可以一起导航。把材料放在读者预期的位置。能从代码生成时就从代码生成。 **解释:理解及原因。** 只讨论一个有界主题,离开产品也能阅读。每个标题前都应能自然加上“关于……”。锚定一个真实的“为什么”问题。提供背景:设计决策、历史、约束和替代方案。只有这里允许表达意见,其他模式不允许。 不要混用模式:教程中不放参考表格,参考资料中不做教程式手把手引导,操作指南中不进行论辩。拆开并互相链接。 ## 面向读者写句子(Google 开发者风格) - 用“你”与读者交流,使用现在时。“will”只用于确实在以后发生的事。 - 说明谁做什么:“the compiler checks”,而非“is checked”。只有执行者未知或无关紧要时才用被动语态。 - 指令写成命令:“点击 Submit。”事实直陈。绝不用“should be done”。 - 条件放在指令之前:“要删除文档,点击 Delete。” - 先写常见情况,再写例外。 - 像一位懂行的朋友。不用流行套话或比喻,指令中不写“please”,操作流程中绝不写“simply”“easy”或“quickly”。如果很简单,读者就不会来到这里。 - 不预告未来功能(“we will soon support...”),也不要连续用同一短语开头。 - 链接文字应说明去向:页面标题或简短描述。绝不用“click here”。优先在当前页面写一句背景,而非把读者链接到别处。 - 标题承载要点,而不只是主题(“先选择模式”,而非“模式”)。英文使用句首大写。任务标题使用裸动词短语(“创建实例”)。概念标题使用名词短语。每页一个 h1,不跳标题层级。 - 有顺序的步骤使用编号列表,其他内容使用项目符号。用完整句子引出列表。各项保持平行。 - 代码用代码字体。UI 元素用粗体。英文使用牛津逗号。删去“etc.”,提前说明列表并不完整。 ## 每次只让读者处理一项陈述(STE 规则) - 每句一条指令。其他内容每句一个想法。 - 指令超过约 20 个英文单词、其他句子超过约 25 个英文单词时,拆开。 - 警告或条件放在其保护的步骤之前:“如果热油接触皮肤,可能造成伤害。” - 保留“the”和“a”:“Remove backup file”有两种读法,“Remove the backup file”只有一种。 - 每个词只有一个含义和一种作用,并保持一致。如果“check”表示检查,就不要同时用它表示约束。 - 每个动作选一个词并一直使用:用“start”,不要这里用“start”那里用“initiate”。 - 流程写成直接命令,不写叙述,也不用被动:“安装组件”,而非“组件必须被安装”。 - 尽可能避免“-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,或两者”,而非“a/b”或“and/or”。 - 同一个东西在所有位置都用同一个名称。一份文档用“the gate”“the ratchet”和“the budget check”指同一事物,会让读者学习三个东西。没有变化的内容不要反复改名。 - 不用习语、口语化表达、拉丁缩写和隐喻。 ## 语气和仓库专属要求 - 对本技能涉及的每份文档应用 **unslop** 技能。低质模式目录由它负责:AI 词汇、填充语、模糊措辞、格式痕迹。 - PR 描述和提交消息也是写作。除 Diátaxis 外,各层均适用。PR 正文应是审查者一分钟内能读完的简报。不要粘贴 swarm 日志、SHA 清单或指标表;改为链接。 - 产品 UI 字符串不是文档。它们应遵循产品的文案指南。 - 代码片段用 tab 缩进。写真实路径。每项数量或目录树声称都必须在使其落地的提交上成立,并附能重新生成它的命令。 ## 完整示例 修改前: > proto 导入的棘轮式预算脚本参数通过 `budget.json` 配置。需要注意,运行 `--write` 会更新已提交预算以反映当前数量,而只有降低预算时才应运行,这一点很重要。如果超出,CI 会失败。 修改后: > `budget.mjs` 从 `budget.json` 读取已提交预算,并统计导入 proto 的文件数量。数量超出预算时,CI 失败。仅在降低预算时运行 `budget.mjs --write`。