simple-english

简明技术英语

ASD-STE100 是航空航天和国防制造商编写维护手册时使用的受控语言。它假设读者疲惫、时间紧迫，而且英语是其第二或第三语言。在此假设下，需要读第二遍才能理解的句子就是缺陷，因此这项标准会去掉所有会导致这种情况的表达方式。

同样的表达方式也会让生成的文字读起来像是机器生成的：轮换使用同义词、对论断模棱两可、用 40 个词承载 3 条事实，以及没有任何测量依据的形容词。为疲惫的读者修正文案，机器生成的痕迹也会随之消失。

写出的每个句子都应能让读者读一遍就理解。

选择任务

改写——生成符合要求的文本。按顺序执行以下步骤。

审查——报告违规之处，但不要更改文本。对每一处违规，给出规则编号、违规文本片段和符合要求的改写。引用任何内容前，请先阅读 references/rules.md：编号并不直观（规则 3.1 讲的是动词形式，而非句子长度），凭记忆引用会导致看似笃定、实则错误的规则编号。

选择严格程度

调用参数：$ARGUMENTS

参数中出现 practical 或 strict 一词，即可确定严格程度；其中的其他内容则是目标文本或目标文本的路径。参数为空表示该技能自动触发，请根据用户请求和下表最后一列决定。

严格程度	参数未指定时的选择依据	应用规则
Practical（默认）	用户希望文档更清晰	所有结构规则。领域术语保持原样——idempotent、backpressure 和 webhook 都是技术名词。
Strict	用户提到 STE、ASD-STE100，或要求符合规范	结构规则和词汇规范。请明确说明，是否获得认证取决于官方词典。本技能不包含该词典。asd-ste100.org 免费提供该词典。

请在输出的第一行注明你选择的严格程度，这样用户只需回复一个词就能纠正，而不必重读整份改写。

步骤 1——判定文本类型

下表中的每条规则都取决于判定结果，因此请先做出判定，并在一段文本中区分这两种类型。

方面	程序性	描述性
作用	告诉读者要做什么	解释某物是什么或有什么作用
动词形式	祈使句——“Restart the pod.”	一般现在时、过去时或将来时
句子限制	20 个词	25 个词
单位	每句话一条指令	每段一个主题，最多 6 句话

快速入门指南属于程序性文本。架构概述属于描述性文本。程序中的注释按描述性文本处理。它只传达信息，不使用祈使句，并遵守 25 个词的限制。

步骤 2——固定词汇

在动笔前完成这一步，不要等到编辑时再做。整份文档中，一个概念只用一个词，让读者只需学习一次。词语一旦变化，读者就会以为含义也变了，并开始寻找两者的区别。

每行选用一个词，除此之外不使用其他词：

• check / verify / confirm / validate / ensure → 任选一个。“Make sure that”最稳妥，因为在 STE 中，check 和 test 是名词。
• config / configuration / settings / options / preferences → 任选一个。
• run / execute / invoke / launch / trigger → 任选一个。
• show / display / render / present / surface → 任选一个。
• delete / remove / drop / destroy → 不同含义各选一个词，并始终区分使用。
• error / issue / problem / failure → 用 error 表示消息，用 failure 表示已停止的操作。

步骤 3——撰写

动词

使用不定式、祈使句、一般现在时、一般过去时、一般将来时，或作形容词的过去分词（“the cached response”）。除此之外，一概不用。复合时态会掩盖时间：“the migration has been running”既没有告诉读者它何时开始，也没有说明它是否已经停止。

-ing 形式只可用作名词（logging、“the mounting bracket”），绝不能作动词，也不能用在句末从句中。“……，allowing you to skip the restart”把事实藏在修饰语里。把它改成一个句子。

使用主动语态。只有在描述性文本中无人知道动作执行者时，才允许使用被动语态。

用动词命名动作，绝不用由动词派生的名词。写“encrypt the payload”，不要写“apply encryption to the payload”。

允许使用的情态动词：can、will、must。禁止使用：should、would、may、might、could。

你写的内容	改为
should（要求）	must
should（建议）	删除，或陈述事实：“X is faster than Y.”
may / might / could	can
would（假设）	重组句子：“If X occurs, Y occurs.”

这条规则在为模型编写的指令中格外有用，因为它一举两得。should 听起来像可选项，在负载较高时就会被忽略。

• 改前： The consumer group has been rebalanced and offsets are being committed.
• 改后： The consumer group rebalanced. The client commits the offsets.

句子

简短，但要完整。不要为了让句子低于字数限制而省略冠词、省略 that 或使用缩写形式——电报式文风更难读，也更难翻译。

• 错误的缩写写法： Ensure bucket exists before upload.
• STE： Make sure that the bucket exists before you upload the file.

每个句子表达一条指令，除非两项操作确实同时发生。如果一句话需要用逗号串起多项内容，就改用纵向列表。用连接词（如“Then”“As a result”）连接相关句子，这样读者就不必自行推断它们之间的联系。

条件和警告

条件放在命令前，并用逗号隔开。如果读者先看到命令，他们可能已经开始操作，之后才看到条件。

• 改前： Increase visibility_timeout if the worker is slow.
• 改后： If the worker is slow, increase visibility_timeout.

对于任何有破坏性的操作，先说明风险级别（可能导致人身伤害时用 WARNING，可能造成损坏或数据丢失时用 CAUTION），再给出命令或条件，最后说明后果。后果必须放在最后，绝不能放在最前面。

• 改前： Note that running the sync with the force option enabled against production may in some cases result in data loss.
• 改后： CAUTION: Do not use --force against production. The flag deletes every row that the source does not contain.

用词和名词链

同一事物在整篇文档中使用同一个名称。不要把名词用作动词（“webhook the event”），也不要把动词名词化（“do a deploy”）。多词名词最多由三个词组成，更长的名词链要用介词拆开。

• 改前： the connection pool acquisition timeout value
• 改后： the timeout for acquiring a connection from the pool

使用美式拼写。如果有单个动词可用，就不要使用短语动词：set up → install 或 configure，go down → decrease 或 stop。

标点和计数

除了分号外，所有常见标点都可以使用——遇到分号时，改写成两个句子。括号可用于引用、缩写和简短的备选项。

计算句子字数时，以下各项均算一个词：数字、数字和单位、缩写、标识符、反引号或引号中的内容、专有名词、标题，以及带连字符的词。括号内的文本总共算一个词。引出纵向列表的冒号会结束当前句子的计数。

kubectl rollout restart deployment/api 算一个词，而不是四个。长标识符不会超出字数限制，因此不要为了节省字数而缩短命令。

看到就删

这些词不传达任何事实。大多数情况下，正确的做法是删掉，而不是替换——如果你说不清一个词增加了什么内容，那它就什么也没增加。

不要写	改为
leverage、utilize	use
in order to / prior to / subsequent to	to / before / after
due to the fact that / in the event that	because / if
ensure	make sure that
is designed to、aims to、serves to	说清它做什么
enables you to、allows you to	you can
facilitate、streamline	help、make faster
functionality	function、feature
plethora、myriad、a wide range of	many，或具体数量
dive into、delve into、explore	read、examine
when it comes to	for
e.g. / i.e. / etc.	for example / that is / 列出具体内容
and/or	选一个，或写成“X、Y 或两者”
out of the box / under the hood	by default / internally
simply、just、easily、seamlessly、effortlessly、gracefully	删除
robust、powerful、comprehensive、performant、blazing fast	删除，或给出具体测量值
it is worth noting that、importantly、crucially	删除并直接陈述事实
as needed、as appropriate	说明条件
handles X gracefully	说清它做什么：“重试两次，然后停止”

这一轮有两条限制。不要为了满足句子长度限制而删掉事实——把句子拆开即可。不要编造数字来替换模糊的形容词。如果没有测量值，就删掉形容词，不要补充其他内容。

以下内容不要改写

代码块、行内代码、标识符、命令、标志、路径、环境变量名、配置键、API 端点、产品名称，以及带引号的错误或日志行。它们都是技术名称。请原样保留，即使它们违反本文件中的所有规则——读者复制“修正后”的命令，可能会遇到新的错误。

提交前自检

改写过程中容易引入错误，请检查自己的草稿。

搜索内容	问题	修正方法
'll 're 've n't it's	缩写	写出完整形式。
has been have been had been has/have + 过去分词	完成时	改用一般过去时或一般现在时。
is being are being	进行时被动语态	改用主动语态和一般时态。
should would may might could	不接受的情态动词	使用情态动词表中的表达。
, making , allowing , enabling , ensuring	用作动词的 -ing 从句	改成带明确主语的新句子。
;	分号	拆成两个句子。
句中出现 if when	命令之后才出现条件	把条件移到句首，并加逗号。
e.g. i.e. etc.	拉丁语缩写	展开写，或列出具体内容。

然后检查：最长的三个句子是否超过 20/25 个词，段落是否超过六个句子，名词链是否超过三个词。最后，搜索第 2 轮中列出的禁用词，并替换所有匹配项。代码和引用文本之外的任何匹配项都属于违规。

示例

修改前 — 一段未经编辑的草稿：

部署后查询变慢。 如果您发现部署后延迟升高，值得检查连接池是否已饱和——这通常是因为长时间运行的查询占用连接所致，从而可能导致新请求无法获取连接。您还应该确认 pool_max 没有保留默认值（10），因为这对于生产工作负载可能不够，并考虑启用语句超时，以确保自动终止失控的查询。

修改后 — 分类为操作步骤，将动词统一为 “make sure that”，将条件前置，每句只包含一条指令：

部署后查询变慢。 长查询占用连接池中的所有连接时，延迟会升高。随后，新请求会等待空闲连接。

1. Make sure that 连接池未饱和。将活动连接数与 pool_max 进行比较。
2. 如果 pool_max 仍为 10，请调高它。默认值对于生产环境来说太低。
3. 设置语句超时。这样，数据库就会在无需操作员介入的情况下停止失控的查询。

句子从 45 个词缩减到不足 20 个。“Checking”“verify”和“ensure”归并为一个动词。两个条件移到了对应命令的前面。pool_max 和 10 保持不变，且各计为一个词。

不适用的情况

STE 的设计目标是去除劝说性内容，因此不适用于营销页面、发布公告和品牌文案。如果用户要求将其用于这类文本，请说明这一点，并提出可以将其用于该页面链接到的文档。

有关错误消息、运行手册、事后复盘、发行说明、提交消息、UI 文案、Agent 指令和翻译准备，请阅读 references/contexts.md ——规则不变，但每种输出的形式各不相同。

请将此文件视为辅助工具，而非认证。ASD 和 STE Maintenance Group 与此文件无关，也没有任何软件能够保证文档通过审核。商标 ASD-STE100 归 ASD 所有，asd-ste100.org 免费提供该标准。

参考资料

• references/rules.md — 53 条带编号的写作规则。在审核中引用规则编号前，请先阅读。
• references/contexts.md — 这些规则如何应用于错误消息、运行手册、事件报告、发行说明、UI 文案、Agent 指令和本地化。