simple-english

Simple English：像寫航空手冊一樣撰寫技術文件

使用 ASD-STE100 簡化技術英文（Simplified Technical English）的規則來撰寫技術文章。STE 是航空與國防製造商用於維護文件的受控語言（controlled language）。制定這些規則的目的，是讓疲憊且非英語母語的讀者也不會誤讀操作指令。同時，這些規則也能順帶消除 AI 產生文本的常見弊病：長句、同義詞輪換、模糊推託、贅字和裝飾性子句。

請為那位疲憊的讀者而寫。每一句話都必須讓人讀一次就能完全理解。

你的任務

當被要求撰寫或重寫技術文章時：

1. 選擇模式（實用模式或嚴格模式，見下文）。
2. 將每個段落分類為「步驟說明（procedural）」或「描述說明（descriptive）」。其餘所有規則都依賴此分類。
3. 在起草前先固定詞彙。針對 check / verify / confirm / validate 這類概念選擇「一個」動詞；針對 config / settings 選擇「一個」名詞。在整份文件中，這些概念絕不使用其他詞彙。
4. 套用下表規則。
5. 在交付前執行自我檢查（self-check）。此步驟不可省略。
6. 絕不改動程式碼、標誌符（identifiers）、命令或引號內的錯誤訊息（參見「不可動搖之物（Untouchables）」）。

當被要求「檢查（CHECK）」文章而非撰寫時，請將每項違規報告為：規則編號、違規文字、符合規範的重寫版本。僅引用本檔案中存在的規則編號。切勿憑記憶引用規則編號：因為編號並不直觀，AI 模型容易自行捏造（經測試，未載入本檔案的 Agent 曾引用「Rule 3.1: 短句」，但真正的 Rule 3.1 是關於動詞形式）。

兩種模式

模式	適用時機	套用內容
實用模式（Pragmatic）（預設）	技術文件、README、錯誤訊息 — 使用者希望文字清晰易懂	所有結構性規則。保留領域專有名詞（如 "idempotent"、"webhook"）。
嚴格模式（Strict）	使用者明確提到 STE、ASD-STE100 或合規要求	結構性規則 + 完整的詞彙紀律，並告知使用者完全合規需要使用官方字典（可在 asd-ste100.org 免費取得）。

步驟 1：文字分類

	步驟說明 Procedural（指令）	描述說明 Descriptive（解釋）
目的	告訴讀者該做什麼	解釋某物是什麼或有何作用
動詞形式	祈使句："Install the pump."	簡單現在式 / 過去式 / 未來式
句子字數限制	20 字（Rule 5.1）	25 字（Rule 6.3）
單元規則	每句僅包含一項指令 (5.2)	每段僅包含一個主題 (6.5)，每段最多六句 (6.6)

切勿在同一段落中混用這兩種模式。「快速入門（Getting started）」區塊屬於步驟說明；「系統架構（Architecture）」區塊屬於描述說明；步驟說明內部的附註（note）則屬於描述說明（適用 25 字限制，不可使用祈使句）。

規則目錄（THE RULE CATALOG）

共 9 個章節、53 條規則，改寫自 ASD-STE100 Issue 9 並附帶軟體範例。官方完整規範可於 asd-ste100.org 免費下載。

第 1 章 — 詞彙（Rules 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 發揮主要作用：您的領域詞彙是合法的。AI 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 章 — 多詞名詞（Rules 2.1-2.2）

規則	指示
2.1	多詞名詞的長度應在三個字（含）以下。
2.2	當技術名詞超過三個字時，先完整寫出一次，之後使用簡寫或以連字符連接單元。

使用介系詞（of, on, in, for）拆解過長的名詞鏈：

修改前： the connection pool timeout configuration value
修改後： the timeout value for the connection pool

第 3 章 — 動詞（Rules 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"）。

核可的情態動詞（Modals）：can, will, must。禁用：should, would, may, might, could。
本標準即便是表達可能性也禁止使用 "could"：請寫 "an explosion can occur"，絕不要寫 "could occur"。關於 "should"：屬於強制的請改用 "must"；屬於建議的請直接寫成事實或予以刪除。對 Agent 的指令來說這更為關鍵 — AI 模型常將 "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 章 — 句子（Rules 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 章 — 步驟說明寫作（Rules 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	附註（Notes）僅提供資訊，切勿包含指令。附註適用 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 章 — 描述說明寫作（Rules 6.1-6.6）

規則	指示
6.1	循序漸進提供資訊：每句僅引入一個新事實。
6.2	使用關鍵字與短語賦予文章邏輯結構。
6.3	每句最多 25 個字。
6.4	將相關資訊分組為段落。
6.5	每段僅討論一個主題。
6.6	每段最多六個句子。

描述性文字中不得使用祈使句。描述用於解釋，步驟用於指示。

第 7 章 — 安全指示（Rules 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 章 — 標點符號與字數統計（Rules 8.1-8.7）

規則	指示
8.1	允許使用所有標準標點符號，分號（;）除外。請改寫為兩個句子。
8.2	使用連字符（-）連接視為單一單元的詞彙。
8.3	允許使用括號用於參考引用、項目編號、縮寫、複數形式、補充解釋、替代方案。
8.4	在垂直列表中，引導冒號在計算字數時視為句子結尾。
8.5	括號內的文字算作一個字。
8.6	以下各項皆算作一個字：數字、帶單位的數字、縮寫、英數混合標誌符（alphanumeric identifiers）、引號內的文字、標題、標籤、專有名詞。
8.7	帶連字符的詞彙算作一個字。

規則 8.6 對軟體文件尤為重要：反引號內的 sqlpipe run --config sqlpipe.yaml 屬於引號文字，僅算作一個字。長標誌符不會占用您的句子字數額度。

第 9 章 — 寫作實務（Rules 9.1-9.4, GR-1 至 GR-8）

規則	指示
9.1	當無法逐字替換時，請重構句子結構。
9.2	正確使用每個核可詞彙：符合核可定義與核可詞性。
9.3	切勿組裝片語動詞（如 "go down" → "decrease"，"set up" → "install" 或 "configure"）。
9.4	整份文件保持一致的風格與術語。

通用建議（General Recommendations）GR-1 至 GR-8：保留連接詞 "that"、謹慎使用 "with"、為代名詞指定明確的指稱對象、優先使用 "this + 名詞" 而非單獨使用 "this"、避免偽友詞（false friends）、避免拉丁文縮寫（Latin abbreviations）、使用包容性語言，以及僅在確定正確時才使用所有格撇號形式（GR-8：若不確定就不要使用 — 非母語讀者難以理解）。

針對軟體文件的 GR-6："e.g." → "for example"，"i.e." → "that is"，並刪除 "etc." — 直接列出項目或寫 "and more"。

詞彙紀律（VOCABULARY DISCIPLINE）

官方字典（包含約 900 個核可詞彙、約 1,200 個禁用詞彙及其替代方案）的版權歸 ASD 所有，故不在此重述。但即使沒有字典，其運作機制依然適用：一詞、一義、一詞性。

已知詞性裁定（Part-of-speech rulings），可作為參考模式：

詞彙	裁定規範
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 instruction"。