simple-english

Simple English：像写航空手册一样撰写技术文档

依据 ASD-STE100 简化英语（Simplified Technical English，简称 STE）规范撰写技术文本。STE 是航空航天及国防制造业用于编写维护文档的受控语言。制定这些规则的初衷，是为了确保即使是一个身心俱疲、且非英语母语的读者，也绝不会误读任何一条操作指令。作为“副产物”，这些规则也能完美消除 AI 生成文本的通病：冗长的句子、频繁更换同义词、模棱两可的用词、废话填充以及修饰性从句。

请始终为那位疲惫的读者而写。确保每句话读一遍就能准确理解。

你的任务

当被要求撰写或改写技术文本时：

1. 选择模式（实用模式 Pragmatic 或严格模式 Strict，见下文）。
2. 分类每个段落为过程性（procedural）或描述性（descriptive）。其他所有规则均依赖于此分类。
3. 起草前统一定义词汇。针对 check/verify/confirm/validate（检查/验证/确认）概念只选定一个动词，针对 config/settings（配置/设置）概念只选定一个名词。在整篇文档中，绝不使用其他词表达同一概念。
4. 应用下方规则目录中的规则。
5. 在交付前执行自查。此步骤为必选项。
6. 绝不动代码、标识符、命令或引用的错误信息（参见“不可触碰项”）。

当被要求“检查”（CHECK）文本而非撰写文本时，请按以下格式报告每项违规：规则编号、违规文本、符合规范的改写方案。仅引用本文件内真实存在的规则编号。切勿凭借记忆引用规则编号：STE 的编号逻辑并不直观，模型极易凭空捏造（测试表明：缺乏本文件的 Agent 曾引用了“Rule 3.1: 短句”；而真正的 Rule 3.1 讲的是动词形式）。

两种模式

模式	适用场景	执行要求
实用模式 Pragmatic（默认）	文档、README、错误信息 — 用户需要清晰易读的文本	执行所有结构规则。保留领域词汇（如 "idempotent", "webhook"）。
严格模式 Strict	用户明确提及 STE、ASD-STE100 或合规要求	执行结构规则 + 完整的词汇约束，并告知用户：如需完全符合规范，需要查阅官方词典（可在 asd-ste100.org 免费获取）。

步骤 1：对文本进行分类

	过程性（操作指令）	描述性（概念解释）
目的	告知读者该做什么	解释某物是什么或如何运作
动词形式	祈使句："Install the pump."（安装泵。）	简单现在时 / 过去时 / 将来时
句子长度限制	20 个词（规则 5.1）	25 个词（规则 6.3）
单元规则	一句只包含一条指令（5.2）	一段只包含一个主题（6.5），每段最多六句话（6.6）

切勿在同一段落中混合使用两种类型。“入门指南”属于过程性内容；“架构设计”属于描述性内容；过程中的“注意”（note）属于描述性内容（限制 25 词以内，不得使用祈使句）。

规则目录

共 53 条规则，分为 9 个章节，改写自 ASD-STE100 Issue 9 并附带软件示例。官方原版文本可前往 asd-ste100.org 免费获取。

第 1 节 — 词汇（规则 1.1-1.14）

规则	说明
1.1	仅使用已认可的词汇、技术名词或技术动词。
1.2	使用已认可词汇时，必须仅作其列表中指定的词性使用。
1.3	使用已认可词汇时，必须仅表达其已认可含义。
1.4	仅使用动词和形容词的认可形式。
1.5	可以将领域词汇作为技术名词使用（如 "webhook"、"commit"、"endpoint"）。
1.6	仅当未经认可的词汇属于技术名词或其一部分时方可使用。
1.7	切勿将技术名词用作动词。
1.8	使用属于你项目或行业的技术名词。
1.9	选定技术名词时，应选择简短明确的词汇。
1.10	切勿使用地区俚语、俗语或黑话作为技术名词。
1.11	一物一名。切勿在此处称其为 "config"，在彼处又称为 "settings"。
1.12	可以将领域动词作为技术动词使用（如 "deploy"、"compile"、"merge"）。
1.13	切勿将技术动词用作名词。
1.14	使用美式英语拼写。

在实用模式下，规则 1.5、1.8 和 1.12 起到了关键作用：你的领域词汇都是合法的。Agent 最常违反的是 1.7、1.11 和 1.13。

改前： You can webhook the event, then do a deploy.
改后： Send the event to the webhook. Then deploy the service.

第 2 节 — 多词名词（规则 2.1-2.2）

规则	说明
2.1	多词名词的词数不得超过 3 个。
2.2	当技术名词确实需要超过 3 个词时，首次使用写出全称，之后使用简称或在单元间加上连字符。

使用介词（of, on, in, for）拆散过长的名词链：

改前： the connection pool timeout configuration value
改后： the timeout value for the connection pool

第 3 节 — 动词（规则 3.1-3.7）

规则	说明
3.1	仅使用词典中给出的动词形式。
3.2	仅允许使用：不定式、祈使句、简单现在时、简单过去时、简单将来时、用作形容词的过去分词。
3.3	过去分词仅能用作形容词（如 "the cached response"）。
3.4	切勿使用助动词构造复杂句式。禁用完成时，禁用 "is to be installed" 这类句型。
3.5	"-ing" 形式仅能作为技术名词或其一部分使用（如 "logging"、"the mounting bracket"）——绝不能用作动词。
3.6	使用主动语态。在描述性文本中，仅在动作发出者未知时方可使用被动语态。
3.7	使用动词而非名词来描述动作（应写成 "compress the file"，而非 "perform compression of the file"）。

认可的情态动词：can, will, must。禁用：should, would, may, might, could。
STE 规范甚至在表达“可能性”时也拒绝使用 "could"：必须写成 "an explosion can occur"，绝不能写 "could occur"。对于 "should"：属于要求的改为 "must"；属于建议的直接表述为客观事实或直接删去。这一点对于 Agent 的指令尤为重要——模型通常会将 "should" 理解为“可选的/可有可无的”。

改前： The migration has completed and the table is being rebuilt.
改后： The migration is complete. The database rebuilds the table.

改前： The flag can be set in the config file, making restarts unnecessary.
改后： You can set the flag in the config file. Then a restart is not necessary.

改前： The temperature must be adjusted.
改后： Adjust the temperature.

第 4 节 — 句子（规则 4.1-4.5）

规则	说明
4.1	编写简短明确的句子。
4.2	切勿为了缩短句子而省略词汇或使用缩写形式。保留冠词，保留 "that"。
4.3	复杂的文本应使用垂直列表呈现。
4.4	在关联主题的句子之间使用连接词（如 "Then"、"As a result"）。
4.5	在适用的名词前加上冠词（the, a, an）或指示形容词（this, these）。

规则 4.2 是专门“反极简主义/反电报体”的规则。STE 的要求是语法结构完整的短句，而不是打字机或电报风格的偷工减料：

错误简写： Ensure file exists before running.
符合 STE： Make sure that the file exists before you run the command.

第 5 节 — 过程性写作（规则 5.1-5.5）

规则	说明
5.1	每句话最多 20 个词（含 WARNING 和 CAUTION 警告信息）。
5.2	一句话只包含一条指令，除非两个动作同时发生。
5.3	使用祈使句撰写指令："Run the migration."
5.4	将必要的先决条件放在命令之前，并用逗号隔开："If the build fails, read the log."
5.5	补充说明（Note）仅提供信息，绝不给出指令。Note 适用 25 个词的长度上限。

改前： You'll want to grab the API key from the dashboard before configuring the client, which you can do under Settings.
改后： Get the API key from the dashboard, under Settings. Then configure the client with this key.

第 6 节 — 描述性写作（规则 6.1-6.6）

规则	说明
6.1	循序渐进地提供信息：每句话引入一个新事实。
6.2	使用关键词和短语赋予文本逻辑结构。
6.3	每句话最多 25 个词。
6.4	将关联信息归类在段落中。
6.5	一个段落只包含一个主题。
6.6	每个段落最多包含六句话。

描述性文本中不得使用祈使句。描述负责解释，过程负责指示。

第 7 节 — 安全指令（规则 7.1-7.3）

规则	说明
7.1	使用明确标识风险等级的词汇（"WARNING" 代表人员伤害，"CAUTION" 代表设备/数据损坏）。
7.2	以清晰的命令或条件作为开头。
7.3	紧接着给出风险或可能导致的结果。

绝不要把操作指令埋在解释说明之后。这一模式可直接迁移至具有破坏力的 CLI 参数、不可逆的数据库迁移以及危险的 API 选项。

改前： Note that data loss may occur in some circumstances if the destructive flag happens to be enabled when running against production.
改后： CAUTION: Do not use the --force flag against production. The flag deletes rows that do not match the source.

第 8 节 — 标点符号与字数统计（规则 8.1-8.7）

规则	说明
8.1	除分号外，允许使用所有标准标点符号。请拆分为两句话。
8.2	使用连字符连接作为一个整体起作用的词汇。
8.3	允许在引用、条目编号、缩写、复数形式、解释及替代方案中使用括号。
8.4	在垂直列表中，作为引导句结尾的冒号在统计字数时视为一句话的终点。
8.5	括号内的文本整体计为 1 个词。
8.6	以下各项分别整体计为 1 个词：数字、带单位的数字、缩写、字母数字混合标识符、引用的文本、标题、标签、专有名词。
8.7	使用连字符连接的词计为 1 个词。

规则 8.6 对软件文档极为重要：行内代码包裹的 `sqlpipe run --config sqlpipe.yaml` 属于“引用的文本”，在统计时计为 1 个词。冗长的标识符不会消耗你的句子字数预算。

第 9 节 — 写作实践（规则 9.1-9.4，GR-1 至 GR-8）

规则	说明
9.1	当逐字替换无法生效时，重构句子结构。
9.2	正确使用每个已认可词汇：符合认可的含义及认可的词性。
9.3	切勿构造短语动词（如 "go down" → "decrease"，"set up" → "install" 或 "configure"）。
9.4	在整篇文档中保持统一的风格与术语。

通用建议 GR-1 至 GR-8：保留连词 "that"；谨慎使用 "with"；为代词指定明确的指代对象；优先使用 "this + 名词" 而非单独的 "this"；避免使用假友词（false friends）；避免使用拉丁语缩写；使用包容性语言；仅在确认完全正确时才使用所有格撇号（GR-8：如果不确定，就不要用——非母语读者觉得难以理解）。

针对软件文档的 GR-6 指南："e.g." 改写为 "for example"，"i.e." 改写为 "that is"，并删去 "etc."——列出具体项或写成 "and more"。

词汇纪律

官方词典（包含约 900 个认可词汇、约 1200 个带替代方案的禁用词汇）版权归 ASD 所有，此处未予收录。但无论是否具备词典，其核心机制均适用：一词、一意、一词性。

以下为已知词性裁定，可作为参考模式：

词汇	裁定规则
test, check, work	仅作为名词使用。写 "Do a test"，而不是 "test the pump"。把 "Check that X" 改写为 "make sure that X"。
oil	在 STE 示例中仅作为名词使用。对于动词，词典给出的认可词是 "lubricate"。
help	仅作为动词使用。对于名词，词典给出的认可词是 "aid"（如 "with the aid of"）。
fall	仅表示“在重力作用下向下移动”，绝不用于表达“减少/下降”（decrease）。
follow	仅表示“跟随/在...之后”，绝不用于表达“遵守”（obey）。应写成 "obey the instructions"。