dlt 仓库中的 ASD-STE100 简化技术英语53 条规则与文档写作实战指南【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool仓库在其.claude/skills/review-vocabulary技能中内置了一套基于 ASD-STE100 Simplified Technical English简化技术英语的写作规范用于统一起草文档、docstring、注释与用户可见错误消息的措辞。本文以 simple-english.md 为主体结合 SKILL.md、simple-english-checklist.md、simple-english-use-cases.md 以及仓库中真实的错误消息实现系统讲解这一套受控语言体系。读完本文你可以掌握如何分类文本程序性/描述性、如何套用 53 条规则、如何执行词汇纪律与交付前自检并理解 dlt 如何把一词一义落到每个错误消息上。STE 是什么dlt 为什么用它ASD-STE100 是航空航天与防务行业用于维护手册写作的受控语言。它的规则设计目标非常明确让一位疲惫、非母语、只读一遍的读者也能正确理解指令。副作用同样有价值——它天然清除 AI 生成文本的常见痕迹长句、同义词轮换、含糊措辞、填充词和装饰性子句。在 dlt 仓库中这套规范不是孤立存在而是被编入可执行的工作流维护者通过/review-vocabulary命令触发审查对分支新增的 docstring、注释、用户可见消息、文档和测试函数名进行统一改写见 SKILL.md。其决策受两个输入约束固定词汇表本文第 7 节展开与simple-english.md 的 53 条规则。值得注意的是该技能被标记为disable-model-invocation: true即模型不能自行触发只能由维护者显式调用因为它会跨数十个文件改写文本并改变 CI 测试 ID。写作的总目标是让每一句话都能经得起一次阅读。原文档对任务的描述凝练为一条原则Write for that tired reader. Each sentence must survive one read.任务流程写前六步当被要求编写或改写技术文本时按以下顺序执行选择模式Pragmatic 务实 或 Strict 严格见下节。为每一段文本分类为 procedural程序性或 descriptive描述性。其他所有规则都依赖这一步。起草前先固定词汇为 check/verify/confirm/validate 这一组概念挑选一个动词为 config/settings 这一组概念挑选一个名词。整篇文档不得混用。套用规则目录中的规则。交付前执行自检。此步不可省略。绝不改动代码、标识符、命令或带引号的错误文本见Untouchables。当任务是检查而非改写时每条违规报告必须给出规则编号、违规原文、合规改写。并且只能引用本文档中真实存在的规则编号——规则编号并不直观模型容易凭记忆编造文档明确记录了实测案例有 Agent 引用了Rule 3.1: short sentences而真正的 Rule 3.1 讲的是动词形式。两种模式Pragmatic 与 Strict模式何时使用应用范围Pragmatic默认文档、README、错误消息——用户只想要清晰的文本全部结构规则。领域词保留原样如 idempotent、webhookStrict用户点名要求 STE、ASD-STE100 或合规结构规则 完整词汇纪律并告知用户完全合规需要官方词典免费下载于 ASD 官网 asd-ste100.org绝大多数日常写作落在 Pragmatic 模式领域词汇合法规则 1.5、1.8、1.12 承担主要工作而 Agent 最容易违反的是 1.7技术名词当动词用、1.11一词多名和 1.13技术动词当名词用。Step 1文本分类procedural / descriptive这是第一条分岔路。混用两种文体是新手最常见的错误一段Getting started是程序性的一段Architecture是描述性的而程序内部的备注是描述性的25 词上限无祈使句。Procedural指令Descriptive解释目的告诉读者做什么解释事物是什么或做什么动词形式祈使句Install the pump.一般现在时/过去时/将来时句子上限20 词Rule 5.125 词Rule 6.3单位规则每句一条指令5.2每段一个主题6.5每段最多六句6.6规则目录53 条规则、9 个章节以下内容根据 ASD-STE100 Issue 9 意译并配以软件领域示例原文53 rules in 9 sections, paraphrased from ASD-STE100 Issue 9 with software examples。Section 1 — 词汇Rules 1.1–1.14规则要求1.1只使用已批准的词汇、技术名词或技术动词1.2已批准词汇只能用其列出的词性1.3已批准词汇只能用其批准的含义1.4只使用动词和形容词的批准形式1.5领域词可作为技术名词使用webhook、commit、endpoint1.6未批准词只能在作为技术名词或其组成部分时使用1.7不得把技术名词当动词用1.8使用你所在项目或行业的技术名词1.9选择技术名词时选简短清晰的1.10区域性、俚语或行话词汇不得作为技术名词1.11一物一名不能此处叫 config彼处叫 settings1.12领域动词可作为技术动词使用deploy、compile、merge1.13不得把技术动词当名词用1.14使用美式英语拼写Before:You can webhook the event, then do a deploy.After:Send the event to the webhook. Then deploy the service.Section 2 — 多词名词Rules 2.1–2.2规则要求2.1多词名词不超过三个词2.2技术名词超过三个词时先完整写一次再给出短形式或用连字符连接各单位用介词of、on、in、for拆开长名词链Before:the connection pool timeout configuration valueAfter:the timeout value for the connection poolSection 3 — 动词Rules 3.1–3.7规则要求3.1只使用词典给出的动词形式3.2只使用不定式、祈使式、一般现在时、一般过去时、一般将来时、作为形容词的过去分词3.3过去分词只能作形容词the cached response3.4禁止用助动词构成复杂结构。禁止现在完成时禁止 is to be installed3.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。标准连表示可能性都拒绝 could应写 an explosion can occur绝不写 could occur。对于 should需求改写为 must建议要么删掉要么作为事实陈述。这一点对 Agent 指令格外重要——模型会把 should 读作可选项。Before:The migration has completed and the table is being rebuilt.After:The migration is complete. The database rebuilds the table.Before:The flag can be set in the config file, making restarts unnecessary.After:You can set the flag in the config file. Then a restart is not necessary.Before:The temperature must be adjusted.After:Adjust the temperature.Section 4 — 句子Rules 4.1–4.5规则要求4.1写短而清晰的句子4.2不得通过省略词或使用缩略来缩短句子。保留冠词保留 that4.3复杂文本使用竖排列表4.4相关主题的句子之间使用连接词Then、As a result4.5名词前按需加冠词the、a、an或指示形容词this、theseRule 4.2 是反电报文体规则STE 是语法完整的短句不是电报风格。错误缩写:Ensure file exists before running.STE:Make sure that the file exists before you run the command.Section 5 — 程序性写作Rules 5.1–5.5规则要求5.1每句最多 20 词警告和注意事项计入5.2每句一条指令除非两个动作同时发生5.3指令用祈使句Run the migration.5.4必要条件放在命令前用逗号分隔If the build fails, read the log.5.5备注只给信息绝不给指令。备注执行 25 词上限Before:Youll want to grab the API key from the dashboard before configuring the client, which you can do under Settings.After:Get the API key from the dashboard, under Settings. Then configure the client with this key.Section 6 — 描述性写作Rules 6.1–6.6规则要求6.1循序渐进给信息每句一个新事实6.2用关键词和短语给文本逻辑结构6.3每句最多 25 词6.4相关信息分组为段落6.5每段一个主题6.6每段最多六句描述性文本中禁止祈使句。描述负责解释程序负责指令。Section 7 — 安全指令Rules 7.1–7.3规则要求7.1用词标明风险等级WARNING 人身伤害CAUTION 财产损坏7.2以清晰的命令或条件开头7.3然后给出风险或可能的结果绝不能把指令埋在解释之后。这个模式直接适用于破坏性 CLI 标志、不可逆迁移和危险的 API 选项——simple-english-use-cases.md 明确指出发布说明中的 Breaking: 条目遵循同样的警告模式命令在前风险在后。Before:Note that data loss may occur in some circumstances if the destructive flag happens to be enabled when running against production.After:CAUTION: Do not use the--forceflag against production. The flag deletes rows that do not match the source.Section 8 — 标点与字数Rules 8.1–8.7规则要求8.1除分号外所有标准标点均合法。分号一律拆成两句8.2用连字符连接作为一个整体单位起作用的词8.3括号可用于引用、编号、缩写、复数形式、解释、替代项8.4竖排列表中引导冒号结束句子并计入字数8.5括号内文本计为一个词8.6以下各项各计一个词数字、带单位的数字、缩写、字母数字标识符、引号文本、标题、标签、专有名词8.7连字符连接的词计为一个词Rule 8.6 对软件文本至关重要反引号中的sqlpipe run --config sqlpipe.yaml是引号文本计为一个词。长标识符不会撑爆你的句子预算。Section 9 — 写作实践Rules 9.1–9.4GR-1 至 GR-8规则要求9.1逐词替换行不通时重构句子9.2正确使用每个已批准词批准的含义、批准的词性9.3不要构建短语动词go down → decreaseset up → install 或 configure9.4整篇文档保持一致的风格和术语通用建议 GR-1 至 GR-8保留连词 that小心 with给代词明确指代对象优先 this noun 而非裸 this避免 false friends避免拉丁缩写使用包容性语言只有在确定正确时才使用所有格撇号GR-8不确定就不用——非母语读者难以理解。GR-6 对软件文档的要求e.g. → for examplei.e. → that is删掉 etc.——要么列出项目要么写 and more。词汇纪律一词一义一义一词性官方词典约 900 个批准词、约 1,200 个禁用词及替代词版权归 ASD 所有不在文档中复现。但其机制可以脱离词典执行一个词、一个含义、一个词性。已知词性裁决词裁决test、check、work只能作名词。Do a test而非 test the pump。Check that X 改写为 make sure that Xoil在 STE 示例中只能作名词。动词义由词典给出 lubricatehelp只能作动词。名词义由词典给出 aidwith the aid offall仅指因重力向下移动绝不可指 decreasefollow仅指随后发生绝不可指 obey。应写 obey the instructionsabove、below仅指物理位置。表达界限用 more than、less than情态动词阶梯你写的STE 改写should需求mustshould建议删除或陈述为事实X is better because Y.may / might / could可能性canmay许可canwould假设重构If X occurs, Y occurs.Slop-to-simple 替换表此表是技能作者自己整理的非 ASD 词典内容映射 AI 生成文档中滥用词到朴素替代词。如果该词不承载任何事实直接删除而不是替换Slop改写为leverage、utilizeusein order totoprior tobeforeensuremake sure thatit is worth noting that删除its important to、crucially删除——陈述事实simply、just、easily、seamlessly、effortlessly删除robust、powerful、comprehensive、performant删除或给出可测量的属性functionalityfunction、featureenables you to、allows you toyou canis designed to、aims to删除——说它做了什么facilitatehelp、make possibledive into、delve intoread、examinewhen it comes toforin the event thatifdue to the fact thatbecauseas needed、as necessary说明条件and/or二选一或写 X, or Y, or bothe.g. / i.e. / etc.for example / that is / 列出项目gracefully handles说明它做了什么重试三次然后停止out of the boxby defaultunder the hoodinternallyblazingly fast、state-of-the-artfast给出数字/删除streamlinemake simpler、make fasterplethora、myriadmanyaddresses the issue、tacklescorrects the fault、removes the error一致性检查将常见的同义词轮换收敛为一个术语Rule 1.11、9.4check / verify / confirm / validate / ensure → 只选一个config / configuration / settings / options → 只选一个delete / remove / drop / destroy → 每个含义一个词保持一致error / issue / problem / failure → 错误用 error失败操作用 failurerun / execute / invoke / launch → 只选一个show / display / render / present → 只选一个Untouchables绝不改动的内容这些属于技术名称Rule 1.5、8.6即使违反词汇规则也必须保持原样代码块、行内代码、标识符、CLI 命令、标志、文件路径带引号的错误消息和日志行产品名、API 端点名、配置键带单位的数字——在句子上限中各计为一个词在 dlt 的实际审查流程中见 SKILL.mdUntouchables 被进一步细化为代码、签名、类型注解、SQL 关键字、反引号内内容、CLI 命令、文件路径、配置键、pytest.param(id...)字符串、fixture 名、参数名以及对生成 SQL 的精确断言全部不在改写范围内。超越文档错误消息、Runbook 与 Agent 指令STE 最初为飞机维护手册而生。同一批特性——一词一义、短句、条件在前——可以迁移到任何读错代价高昂的文本。到 Issue 8 结束时64% 的注册 STE 用户已来自航空航天与防务之外。每个用例都规定了模式与改编方式错误消息与 CLI 输出程序性最高价值目标模式为——陈述发生了什么一般过去时、已知则说明原因、给出修复的命令或条件。示例Connection to the database failed. The password for userappwas not correct. SetDB_PASSWORDand connect again.。禁止 Oops、禁止 Please ensure、禁止道歉式填充。Runbook 与标准操作流程严格倾向程序性每步祈使、每步一条指令、条件在前警告放在步骤之前命令在前、风险在后20 词上限严格执行。事故报告与复盘描述性只用一般过去时。We have identified an issue that may have impacted 改写为 Between 14:02 and 14:31 UTC, 12% of requests failed.。STE 禁止含糊措辞——报告只陈述已知其余写 unknown。提交消息与 PR 描述描述性正文 祈使式主题行套用替换表和 25 词上限删除 this PR aims to。API 变更日志与发布说明描述性一条目一变更Breaking: 条目遵循警告模式。AI Agent 指令prompts、AGENTS.md、skills程序性系统提示词是由一个无法提问的读者执行的过程——正是 STE 为之设计的读者类型。每句一条指令使规则可独立引用、难以半执行一词一义防止模型把 check、verify、validate 当成三种不同操作条件在前优于尾部条件模型会丢弃尾部条件禁用 should。客服宏与状态页更新描述性25 词上限The API was down for 18 minutes. Uploads made during this time were saved and will process today.。翻译与本地化预处理严格STE 的原始用途一词一义加完整语法消除大多数翻译歧义。UI 文案与空状态程序性硬长度限制按钮和标签属于技术名称豁免正文遵循规则No projects yet. Create a project to start.。STE 不适用之处营销页、发布博客、品牌文案。STE 故意删除说服力。此时用你自己的语气写——再用 STE 改写落地页链接的文档。dlt 仓库中的落地实例错误消息的 STE 形态dlt 的技能定义了一条跨所有组的全屋风格规则错误消息中dlt是句子的主语——这是带具名施动者的主动语态Rule 3.6的落法dlt cannot join…、dlt cannot determine…。仓库中的真实错误消息完全符合发生了什么 → 原因 → 修复指令的三段式。例如 client.py 中的_no_data_location(reason)helper它把一个短原因包装进框架句 dlt cannot determine the data location of destination。def _no_data_location(self, reason: str) - NoReturn: raise DestinationTerminalException( dlt cannot determine the data location of destination f because {reason} )技能明确警告要按组装后的完整句子计数而不是按片段计数。一个四词的 reason 可能把组装后的句子推过 20 词上限。同时该 helper 在各目标配置中得到了广泛复用例如 postgres/configuration.pythe configuration has no host、the configuration has no database、filesystem/configuration.pythe configuration has nobucket_url、ducklake/configuration.pythe configuration has no ducklake catalog以及 cryptography.py 中的 dlt cannot decrypt the token. The encryption key does not match. —— 原因与修复指令清晰分离。技能还强调消息必须保留其修复建议许多错误以指令结尾Materialize the dataset…、Set a permanentpipeline_salt…改写时要把措辞改进为祈使式、条件在前、20 词内、每句一条指令绝不删除修复建议也绝不无中生有——修复建议需要字符串未插值的真实事实支撑。改写消息的陷阱测试断言测试会按错误文本匹配SKILL.md 的 The trap 一节记录了一个真实教训matchcannot be determined的断言在框架句被改为 dlt cannot determine the data location 后依然通过因为子串仍然命中。参数化测试还会把断言藏在远离消息定义的地方。因此必须greptests/中的match、in str(exc、in str(reject检查否定断言assert can join not in ...对 cannot join 依然通过因为 can 后无空格最后无论如何都要跑测试套件——grep 只是起点不是检查。Snippet 文件既是测试又是文档使用!--DLT_SNIPPET ./x_snippets.py::name--的页面拉取的是真实测试中的真实代码docs/pyproject.toml会收集*snippets.py并在 docs CI 中执行。因此同一文件接受双重审查代码按测试规则审#注释按用户可见文档审。一个直接后果是snippet 内的注释会渲染给读者过时或错误的注释是文档 bug 而非代码卫生问题同时绝不能为了满足散文规则而改动 snippet 代码——改代码就是改 CI 实际运行的内容。此外围栏代码块不是snippet它未经测试存在与 API 漂移的风险应标记为未验证。固定词汇表dlt 特有裁决技能在通用规则之上定义了五组领域词汇组内自洽互不依赖G1 — 数据访问与位置access 是动词不是名词不写 data access数据物理所在写 data location禁用 reach/reaches/get to 等。G2 — Attach 与外部数据集TAttachInfo对象写 attach infoTAttachStatement写 attach statementSQL 关键字ATTACH必须带反引号禁止用 descriptor 指代TAttachInfo但 Python descriptor 协议中的 descriptor 合法。G3 — 转换与物化lazy materialization延迟物化与 eager materialization立即物化是唯一合法用法model job 是工件lazy materialization 是路径二者不可混淆。G4 — 标识符与 SQL 生成拼写为 case-fold带连字符代码标识符casefold_identifier保留原名。G5 — 配置与凭据解析后的设置对象写 configconfiguration error 仅在指代ConfigurationValueError时保留。此外有一份任何组都不得替换的合法技术名词清单attach、attach alias、attach info、attach statement、catalog、config、data location、dataset、destination、duckdb、iceberg、materialization、model job、pipeline、relation、scanner、vended。新增术语或新组有严格的八步流程选组、grep 调研用法、推导禁用集、核对上游接口、命名误报如 descriptor、规定词性、用 grep 验证禁令宽度、更新文件——每一步都要求证据而非直觉。交付前自检不可省略simple-english.md 规定四步自检配套的 simple-english-checklist.md 提供完整验证流程数句子数三个最长句子的词数超过 20/25 上限就拆分。搜索草稿ll、re、s缩略、has been、have been、should、逗号后的-ing动词、分号。搜索每个if和when每个都必须位于句子开头、命令之前。Increase the timeout if the network is slow → If the network is slow, increase the timeout.搜索未选定的动词检查第 3 步写前没有选中的 check/verify/confirm 集合词把每个命中替换为你选定的那个动词。清单文件将检查按机械性到判断性排序机械检查可搜索包括缩略、完成时、未批准情态动词、进行时被动、-ing从句、分号、拉丁缩写、填充词、句中条件可数检查包括句长、段长最多六句、多词名词链超三个词拆开、每句指令数判断检查包括文本分类、语态、条件位置、同义词轮换、警告格式、语法完整性、Untouchables 完整性。dlt 的审查工作流SKILL.md在此基础上增加了工程化验证审计阶段只提议不改动按区域拆分 diff 给子 Agent文件集不得重叠每条发现给出file:line、规则编号、当前文本、改写应用阶段分两批Phase A 处理 docstring/注释/重命名/断言修复/内容修正Phase B 处理消息字符串因二者共享文件无法并行验证阶段依次执行——AST 去 docstring 对比注释不进 AST任何差异意味着代码或字符串被改动、四步自检、make formatBlack 无变更报告、make lint、跑测试此步不可省略。完整示例一次真实的 STE 改写Before未经编辑的 AI 真实输出Connection timeouts.If sqlpipe hangs or fails withdial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a security group or firewall rule blocking the connection. If youre connecting to a managed database (RDS, Cloud SQL, etc.), confirm the instance allows connections from sqlpipes IP. You can also try increasingsource.connect_timeout_secondsin your config, since a slow network path can trip the default timeout even when the connection eventually succeeds.After分类为程序性动词选 make sure条件在前每句一条指令Connection timeouts.sqlpipe stops withdial tcp: i/o timeoutwhen it cannot reach the Postgres port (5432 by default).Make sure that the host that runs sqlpipe can reach the Postgres port. A firewall or security group usually blocks it.If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.If the network is slow, increasesource.connect_timeout_secondsin the configuration.改了什么40 词的句子拆到 20 词以内youre 展开check/confirm 收敛为 make sure that每个条件移到命令之前etc. 移除代码和错误字符串保持原样。适用边界STE 服务于技术事实与指令。不要把它用在营销文案、博客语气或品牌写作上——它刻意删除说服力。当用户对营销文本提出 STE 要求时应当说明这一点并建议改为对文档应用。同时需明确该技能是非官方辅助工具与 ASD 或 STEMG 无隶属或背书关系任何工具都无法保证 STE 完全合规ASD-STE100 是 ASD 的注册商标官方标准可在 ASD 官网免费下载。检查模式交付报告时若用户要求 STE 合规需以清单文件规定的声明结尾No tool can guarantee ASD-STE100 compliance. Final approval rests with the writer.延伸阅读SKILL.md — 技能入口触发方式、作用域、固定词汇表 G1–G5、审查工作流与 AST 验证脚本simple-english-checklist.md — 完整验证清单供检查模式与最终审计使用simple-english-use-cases.md — 长文改编错误消息、runbook、事故报告、提交消息、UI 文案、i18nclient.py —_no_data_location框架句的真实实现postgres/configuration.py — 消息保留修复建议的多目标实例之一【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考