technical-writing

技术写作

目标是写出让疲惫的工程师读一遍就能理解的内容。四个层次可以帮你做到这一点，每个层次对应一个问题：这是什么类型的文档？句子如何称呼读者？每个句子承载多少内容？有没有句子可能被理解成两种意思？四个层次都要应用。

有三条规则高于这些层次：

• 删掉每个不起作用的词。 如果去掉某个词，句子依然成立，那就删掉它。“为了”就是“为”。“需要注意的是”毫无作用。
• 用简短、日常的词。 用“使用”，不用“利用”。用“帮助”，不用“促成”。用“做”，不用“执行”。长词必须用精准表达来证明它值得占用那么多字。
• 如果某条规则让句子变得更糟，就换种方式修改句子，或者保留原样。 这些规则是为读者服务的。句子遵循了所有规则，读起来却像机器写的，那就是失败。

代码库就是词表。写出实际的符号、文件、标志或命令名称，不要用同义词或描述来代替。

不要凭空造术语。用开发者会脱口而出的词：“移动”“删除”“只会减少的预算”，而不是“疏散”“棘轮”或“终局”。如果文档首次提到某个命名模式时解释了它的含义，就可以使用。请在回复中提议一个新的违规词及其替换词，将其作为补充添加到 unslop 的抽象隐喻规则中，并附上 diff。不要编辑该技能。

变换节奏

这些层次决定文档说什么，以及每个句子承载多少内容。即使文档符合所有层次，读起来仍可能像机器写的：每个句子都短促，没有观点，也没有具体内容。

• 有意交替句子长度。短句能突出重点。较长的句子可以从容地讲清一项事实及其条件或后果。
• 每句一个想法，不代表每句长度都一样。拆分承载两个想法的句子。保留承载一个想法的长句。
• 在文档类型允许的地方表达观点。解释文档要权衡利弊，所以要说清你的判断，而不是只列出优缺点。参考文档则应保持客观。
• 具体胜过空泛。不要说“架构变更可能导致问题”，而要说“重命名列会导致构建失败”。

先选择模式（Diátaxis）

一篇文档，一种模式。回答两个问题即可确定：内容是指导行动（做事）还是帮助理解（思考），以及它是服务于学习还是工作。

• 行动 + 学习：教程。
• 行动 + 工作：操作指南。
• 理解 + 工作：参考资料。
• 理解 + 学习：说明。

可用这套指南判断整篇文档，也可判断单个句子。

教程：通过实践学习。 你是老师。学员能否成功是你的责任，不是他们的责任。开篇要说学员将构建什么，而不是他们将“学到什么”。每一步都要尽早、频繁地产生可见结果。告诉他们应该看到什么：预期输出、提示词变化、日志行。把解释精简为一个从句和一个链接。不要在教学过程中插入暂停。保持具体。用“我们”来写，并采用命令式表达：“首先，执行 x。现在，执行 y。”

操作指南：逐步实现目标。 解决人们遇到的问题，而不是机器能够执行的操作。假定读者具备相应能力。跳过教学。只写行动：不插入离题内容、背景介绍，也不为追求完整而面面俱到。相关内容改用链接指向。允许分支和判断：“如果你想要 x，就执行 y。”按任务命名指南：“如何校准雷达阵列”，而不是“雷达阵列校准”。

参考资料：供查阅的事实。 只描述，不做其他。不要给出指令、劝说或表达观点。保持客观、完整、明确。陈述事实、选项、限制和错误，不要含糊其辞。让结构与所描述的对象保持一致，以便读者能同时浏览代码和文档。把内容放在读者预期的位置。尽可能从代码生成内容，确保内容准确。

说明：理解及其缘由。 聚焦一个范围明确的主题，即使脱离产品也易于阅读。每个标题前面都应能自然加上“关于……”。围绕一个实际的“为什么”问题展开。提供背景信息：设计决策、历史、限制和替代方案。只在此处表达观点。

不要混合模式：不要在教程中放参考表格，不要在参考资料中手把手教学，也不要在操作指南中争辩。拆分内容并添加链接。

来源：diataxis.fr，获取于 2026-07-18。

面向读者写句子（Google 开发者风格指南）

• 用现在时以“你”为读者写作。只有确实会在之后发生的事才用“将”。
• 明确说明谁做什么：“编译器会检查”，而不是“会被检查”。只有在执行者未知或无关紧要时，才可以使用被动语态。
• 用命令式表达指示：“点击 Submit。”直陈事实。不要写“应当完成”。
• 把条件放在指示前面：“如需删除文档，请点击 Delete。”读者可以跳过不适用的内容。
• 先说常见情况，再说例外。
• 语气要像一位知识渊博的朋友。不要使用行业套话、比喻或指示中的“请”，也不要在操作步骤中使用“只需”“轻松”或“快速”。如果这件事很简单，读者就不会在这里了。
• 不要预告未来（“我们很快会支持……”），也不要让连续的句子以相同的短语开头。
• 链接文字要说明链接指向何处：使用页面标题或简短描述。不要写“点击这里”。相比链接到其他页面，优先在当前页面提供背景说明。
• 标题要表达重点，而不只是主题（“先选择模式”，而不是“模式”）。使用句首字母大写格式。任务标题用裸动词短语（“创建实例”）。概念标题用名词短语。每页只用一个 h1，不要跳过标题级别。
• 按顺序执行的内容用编号列表，其他内容用项目符号列表。用完整句子引出列表。列表项的结构要保持平行。
• 代码使用代码字体。UI 元素使用粗体。使用顿号。删除“等等”，并在开头说明列表是否不完整。

来源：developers.google.com/style，获取于 2026-07-18。

让陈述一次只表达一层意思（STE 规则）

• 每个句子只写一条指令。其他地方的每个句子也只表达一个意思。
• 将超过约 20 个单词的指令，以及超过约 25 个单词的其他句子拆开。
• 将警告或条件放在其所约束的步骤之前：“如果热油接触皮肤，可能会造成伤害。”
• 保留“the”和“a”：“Remove backup file”有两种读法。“Remove the backup file”只有一种读法。
• 每个词只表达一种意思、只承担一种作用，并始终保持一致。如果“check”表示检查，就不要再用它表示约束。
• 每种操作选用一个词，并始终使用这个词：“start”，不要这里用“start”、那里用“initiate”。
• 将操作步骤写成直接命令，绝不写成叙述，也不使用被动语态：“Install the component”，不要写成“the component must be installed”。
• 尽量避免使用“-ing”形式的词。它们承担的语法作用太多，容易造成误读。

来源：asd-ste100.org（第 9 期，2025 年），获取于 2026-07-18。编号规则和词典收录在规范 PDF 中。以上原则是可迁移的核心内容。

确保每个句子都只有一种解读（全球英语）

• 让“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”让 Phase 2 缺少动词。为它补上动词。
• 保留表示结构关系的小词。“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”指代同一事物，就会让人以为有三种东西。编辑时，改写未发生变化的句子，成本也一样。不要反复改写未变更的内容。
• 避免习语、口语、拉丁文缩写和比喻。非母语读者、译者和 Agent 都最容易理解直白的表达。

来源：Kohl，《全球英语风格指南》（SAS Press）。指南文本摘自 Internet Archive 和 SAS 示例章节，获取于 2026-07-18。

语气和代码仓库具体要求

• 对本技能涉及的每份文档都应用 unslop 技能。该技能负责维护低质量文本模式目录，包括 AI 词汇、填充语、模糊措辞和格式痕迹。
• PR 描述和提交消息也属于写作。除 Diátaxis 外，所有规则都适用于它们。PR 正文应是一份简报，审阅者可在一分钟内读完。不要粘贴 swarm 日志、SHA 列表或指标表格。请链接到它们。
• 产品 UI 字符串不属于文档。应遵循产品的文案指南。
• 代码片段使用制表符缩进。使用真实路径和真实符号。确保每项数量或目录树相关陈述在提交时都准确无误，并附上用于重新生成它们的命令。

示例

之前：

proto 导入限额脚本的参数通过 budget.json 配置。请注意，只有在降低限额时，才应使用 --write 运行脚本，以更新已提交的限额。如果超出限额，CI 就会失败。

之后：

budget.mjs 从 budget.json 读取已提交的限额，并统计导入 proto 的文件数量。如果数量超出限额，CI 就会失败。仅在降低限额时运行 budget.mjs --write。