simplified-technical-english

Simplified Technical English

このスキルは、Simplified Technical English（STE）で文章を書くためのものです。 STEは、技術文書向けの統制言語です。 仕様書ASD-STE100には、53の文章作成規則と、使用が承認された単語の辞書が記載されています。 STEで書かれた文章は、英語をあまり知らない読者にもわかりやすいものです。

技術的な文章を書くときは、すべてこのファイルの規則に従ってください。 このファイルの規則を最優先してください。 規則の全容はreferences/writing-rules.mdに記載されています。 使用が承認された単語はreferences/word-list.mdに記載されています。

適用範囲

技術文書、手順書、マニュアル、説明書、レポート、エラーメッセージ、技術的な題目に関する回答など、技術的な出力にはSTEを適用してください。

以下にはSTEを適用しないでください。

• マーケティング文やブランドに関する文章
• 詩、物語、会話
• コードブロック、識別子、コマンド、ファイルパス、引用されたエラーメッセージ
• 引用文、製品、部品、文書の正式名称

ユーザーが別の文体を指定した場合は、その指示を優先してください。

ステップ1：文章を分類する

文章を書く前に、各部分を次のように分類してください。

• 手順文は、読者に何かをするよう指示します。例：「4本のボルトを取り外します。」
• 説明文は、情報を伝えます。例：「ポンプはエンジンに燃料を供給します。」

この2種類には、それぞれ異なる制限があります。1つの段落に両方の種類を混在させないでください。

ステップ2：動詞の規則に従う

• 使用できる動詞の形は、不定詞、命令形、単純現在形、単純過去形、willを使う未来形、形容詞としての過去分詞のみです。
• 動詞の-ing形は使用しないでください。承認された-ing形の単語は、mating、missing、remaining、lighting、opening、routing、servicing、duringのみです。
• 過去分詞に助動詞を付けないでください。「the operator has adjusted the linkage」ではなく、「the operator adjusted the linkage」と書いてください。
• 能動態を使ってください。「the circuits are connected by a relay」ではなく、「a relay connects the circuits」と書いてください。
• 手順では命令形を使ってください。「Set the switch to ON.」と書いてください。
• 動作の主体がない場合は、主語に「you」または「we」を使ってください。
• 助動詞として使用できるのは「can」、「must」、「will」のみです。「should」、「would」、「may」、「might」、「shall」は使用しないでください。
• 「is」または「are」の後に続く過去分詞は状態を表し、使用できます。「The wires are disconnected.」

ステップ3：文の規則に従う

• 手順文は最大20語にしてください。
• 説明文は最大25語にしてください。
• 段落は最大6文とし、題目は1つだけにしてください。
• 各文には指示を1つだけ記述してください。同時に起こる場合に限り、2つの動作を記述できます。
• 各文で扱う題目は1つだけにしてください。
• 条件を命令の前に置く場合は、条件の後にコンマを付けてください。「If the light comes on, stop the engine.」
• 冠詞、主語、動詞、および接続詞「that」を省略しないでください。「make sure that the file exists」と書いてください。
• 短縮形は使用しないでください。「don't」ではなく「do not」と書いてください。
• セミコロンは使用しないでください。2つの文に分けてください。
• 複雑な内容には縦型リストを使ってください。「not」を含むコマンドのリストでは、各項目で「not」を繰り返してください。

ステップ4：単語の規則に従う

• references/word-list.mdで承認された単語、技術名称、技術動詞のみを使用してください。
• 技術名称は、対象分野の部品、ツール、材料、システム、文書、用語の正式名称です。例：「engine」、「firewall」、「torque wrench」、「SKILL.md」。
• 承認された単語は、指定された品詞でのみ使用してください。「Test」は名詞であり、動詞ではありません。「test the system」ではなく、「do a test」と書いてください。
• 全文を通して、1つの項目には1つの名称を使ってください。同じ項目に対して複数の名称を使わないでください。
• 名詞の連結は最大3語にしてください。長い連結は「of」、「on」、「in」、「for」を使って分けてください。
• 句動詞は使用しないでください。「put out the fire」ではなく、「extinguish the fire」と書いてください。
• 曖昧な語は使用しないでください。具体的な数量、名称、動作を書いてください。
• アメリカ英語の綴りを使ってください。
• よく使われる置き換え表現はreferences/substitutions.mdに記載されています。

ステップ 5: 安全指示を正しく書く

• 人への負傷または死亡のリスクには「WARNING」を使用します。
• 物への損傷のリスクには「CAUTION」を使用します。
• 簡単なコマンドまたは条件から始めます。次に、リスクを示します。
• 例: 「WARNING: コネクタに触れないでください。コネクタには危険な電圧がかかっている可能性があります。」

ステップ 6: テキストを確認する

テキストを書いたら、テキストを確認します。次の手順を実行します:

1. スクリプトを実行できる場合は、次を実行します: python3 scripts/ste_check.py --mode <procedural|descriptive> <file>。
2. スクリプトを実行できない場合は、以下のチェックリストを手動でスキャンします。
3. 各エラーを修正します。
4. テキストをもう一度確認します。テキストにエラーがなくなるまでのみ停止します。

手動スキャンのチェックリスト:

• セミコロンと短縮形を見つけます。それらを削除します。
• 過去分詞の前にある「has」、「have」、「had」を見つけます。単純過去時制を使用します。
• 「should」、「would」、「may」、「might」、「shall」を見つけます。それらを置き換えるか、削除します。
• 承認されておらず、技術名にも含まれていない「-ing」の単語を見つけます。それらを書き換えます。
• 受動態を見つけます。エージェントを主語にするか、命令形を使用します。
• 最も長い文の単語数を数えます。長すぎる文を分割します。
• 各段落の文の数を数えます。6 文を超える段落を分割します。
• 承認されておらず、技術名でもない単語を見つけます。それらを置き換えます。

チェックツールはすべてのエラーを見つけることはできません。 ツールは、ある単語が承認された意味で使われているかどうかを知ることはできません。 また、あなたの単語を references/word-list.md と比較する必要があります。

参照ファイル

• references/writing-rules.md — すべての 53 のルールと 4 つの推奨事項、例付き。文書を書き換えるとき、またはルールが明確でないときにこのファイルを読んでください。
• references/word-list.md — 869 の承認された単語とその品詞および形態。
• references/substitutions.md — 頻繁に使われる未承認の単語の置き換え、および技術名と技術動詞のカテゴリ。
• examples/before-after.md — STE への変更前と変更後のテキストの例。

根拠

このスキルの出典は ASD-STE100 Issue 7 (2017) です。 ASD は仕様の新しい Issue をリリースします。 仕様は https://www.asd-ste100.org から無料で入手できます。 このスキルは公式の ASD 文書ではありません。 このスキルは、あなたのテキストが公式仕様に完全に従うことを保証することはできません。 著作権情報については NOTICE.md を参照してください。