technical-writing

技术写作

加粗或用反引号括起来的技能名称，或以 /<name> 的形式运行的技能，指的是此技能目录旁的 ../<name>/SKILL.md 文件；不带前缀的原则名称指的是 ../principle-<name>/SKILL.md。读取该文件并遵循其中的要求。大多数 pstack 技能仅供用户使用，因此你的技能工具无法加载它们。

写作要让疲惫的工程师读一遍就懂。应用全部四层要求。

有三条规则高于这四层：

• 删掉每个不起作用的词。 如果句子删掉某个词后仍然成立，就删掉它。“为了”可以改成“要”。“需要注意的是”什么也没说。
• 用简短、日常的词。 用“使用”，别用“利用”。用“帮助”，别用“促进”。用“做”，别用“执行”。长词必须用精确性证明它值得占用更多篇幅。
• 如果某条规则让句子变差，就换种方式改写，或者保持原样。 句子即使符合所有规则，读起来像机器写的，也算失败。

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

不要生造术语。用开发者口头会说的话：“移动”“删除”“只会递减的预算”，而不是“撤离”“棘轮”或“终局”。如果文档首次解释了某个命名模式的含义，就可以使用。请在回复中提出一个新的违规词及其替换词，作为对 unslop 抽象隐喻规则的补充，并附上差异内容。不要修改该技能。

变换节奏

文档即使符合所有层面的要求，读起来仍可能像机器写的：句子都短促、没有观点，也缺少具体内容。

• 有意识地混合句子长度。短句能强调重点，长句则能连同条件或结果一起交代事实。
• 一句话只表达一个想法，不代表每句话都要一样长。拆开承载两个想法的句子，保留只表达一个想法的长句。
• 在文体允许时表达观点。说明文要权衡取舍，因此要说清你的判断，而不是罗列优缺点。参考文档则保持客观。
• 具体胜过空泛。不要写“架构变更可能导致问题”，而要写“列重命名会导致构建失败”。

先选择模式（Diátaxis）

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

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

可以用这个指南审视整篇文档，也可以审视单个句子。

教程：在实践中学习。 学习者能否成功是你的责任，不是他们的。开篇说明学习者将构建什么，而不是他们将“学习”什么。每一步都要尽早、频繁地产生可见结果。告诉他们应该看到什么：预期输出、提示词的变化、日志行。把说明压缩成一个分句，并附上链接。保持具体。用“我们”的口吻，以命令句写作：“首先，执行 x。现在，执行 y。”

操作指南：按步骤实现目标。 解决人的问题，而不是机器能执行的操作。假设读者具备能力，跳过教学。只写行动：不岔开话题，不讲背景，不为完整而面面俱到。相关内容改用链接。允许分支和判断：“如果你想要 x，就执行 y。”按任务命名指南：“如何校准雷达阵列”，而不是“雷达阵列校准”。

参考：供查阅的事实。 只做描述。不提供指示，不劝说，不表达观点。内容要简洁、完整、明确。陈述事实、选项、限制和错误，不要含糊其词。让文档结构与所描述内容的结构一致，以便读者能同时浏览代码和文档。把内容放在读者预期的位置。尽可能从代码生成。

说明：理解原理与原因。 聚焦一个范围明确的主题，即使脱离产品也易于阅读。每个标题前面都可以自然地加上“关于……”。围绕一个真实的“为什么”问题展开。提供背景：设计决策、历史、限制和替代方案。只有这里可以表达观点。

不要混用模式：教程中不要放参考表，参考文档中不要手把手教学，操作指南中不要争辩。应拆分内容并添加链接。

直接面向读者写句子（Google 开发者风格）

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

让陈述一次只表达一个意思（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”形式的词。

不要让句子存在两种理解（全球英语）

• 让“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，或两者”替代“a/b”或“and/or”。
• 始终用同一个名称指代同一事物。如果一份文档用“the gate”“the ratchet”和“the budget check”指代同一事物，就会让读者以为有三个事物。没有变化的内容不要反复改写。
• 不要使用习语、口语表达、拉丁语缩写或隐喻。

语气和代码库具体要求

• 对此技能涉及的每份文档应用 unslop 技能。该技能负责处理冗余表达模式目录，包括 AI 词汇、填充语、模糊措辞和格式特征。
• 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.