writing-simplified-technical-english

编写简明的技术英语

ASD-STE100 是一项受控语言标准。 航空航天和国防行业制定这项标准，是为了避免技术人员误读维护说明。 它消除了最容易引起误读的两大因素：一词多义，以及句子结构可能有多种解读。

同样的规范也能解决 Agent 撰写文本时常见的问题。 Agent 输出往往内容正确，却难以阅读：句子冗长、层层推测、使用被动语态，还轮番使用同义词，让同一个操作看起来像三个操作。 读者无法向作者询问，因此，歧义至少会让读者重读一次，最坏则会导致错误操作。

写作时请遵循以下规则。 不要先写一份晦涩的草稿，再事后修改。

适用场景

将这些规则用于需要人或其他 Agent 据此采取行动的文本：

• 报告、调查结果和摘要。
• PR 描述、提交消息和代码注释。
• 传递给其他 Agent 的说明和提示词。
• 工具描述、错误消息、空状态和日志行。

不要将这些规则用于风格表达本身就是目的的文本：营销文案、博客文章或任何说服性内容。 STE 的风格刻意平实。 引文也应保持原样。 引用用户内容、日志或文档时，请照录原文。

规则

规则	应做	不应做
一个词只表达一种含义	每个操作选用一个动词，并始终使用这个动词	对同一操作轮换使用 "check"、"verify" 和 "confirm"
每个词只作一种词性	"Apply oil to the valve"	"Oil the valve"
使用主动语态	"The worker deletes the file."	"The file is deleted."
使用简单时态	"We received the report."	"We have received the report."
每个句子表达一个观点	"Open the file. Read line 3."	"Open the file and read line 3, then check it matches."
控制句子长度	说明不超过 20 个词，描述不超过 25 个词	连续使用从句
控制名词组合	不超过 3 个词（"fuel pump valve"）	"high pressure fuel pump inlet valve assembly"
不省略必要成分	保留主语、动词和冠词，即使句子会更长	"Files not backed up will be lost"，因为这句话没有说明哪些文件
最多使用一个不确定表达	"The client version is probably out of date."	"An error may have occurred which could be caused by..."
段落	每段只讲一个主题，且不超过 6 个句子	一个段落包含多个主题
列表	有 3 个或更多步骤或条件时使用列表	把一连串步骤藏在一个句子里
术语	保留所需的技术术语，并定义一次	使用读者从未见过的内部名称

PostHog 的内部风格指南在这些规则之上；两者有冲突时，以内部风格指南为准。 我们使用美式英语、句首字母大写的标题格式，并使用牛津逗号。 我们不使用 em dash。

如何重写

1. 通读一遍文本，理解其含义。了解文本必须保留哪些内容后，再开始重写。
2. 逐句检查。指出每句话违反了哪条规则。
3. 重写句子，修正违规之处。保留所有事实、数字、条件和限定语。
4. 再次依据规则检查结果。重写时常常会引入新的长句。

准确性胜过简洁性。 如果缩短句子会删掉安全条件、范围限定语或数字，就保留较长的句子，并说明原因。

如果文本已经符合规则，就说明这一点。 不要更改符合规则的文本。

自检

发送文本前，通读一遍并自问：

• 有没有句子超过 25 个词？
• 有没有句子包含两条指令？
• 同一操作是否用了两个不同的动词来描述？
• 被动句能否明确指出执行者？
• 对于刚加入且不了解上下文的读者，下一步该做什么是否清楚？

参考资料

• references/writing-rules.md：表格背后的详细说明，以及相关来源。
• references/before-after.md：重写示例，包括 Agent 输出。