simple-english

簡易テクニカル英語

ASD-STE100 は、航空宇宙および防衛分野のメーカーが整備マニュアルを作成する際に使用する制御言語です。読者が疲れていて、時間に追われ、英語を第二言語または第三言語として読んでいることを想定しています。この前提では、読み直さなければならない文は不備です。そのため、この規格では、読み直しの原因となる構文をすべて排除します。

こうした構文こそが、生成された文章を生成文らしく見せる要因です。同義語を次々に変えること、断定を避けた主張、3つの事実を含む40語の文、裏付けとなる測定値のない形容詞などです。疲れた読者のために文章を直せば、機械が書いたような不自然さもなくなります。

一度読めば理解できる文を書いてください。

作業を選ぶ

書き換え — 規則に準拠した文章を作成します。以下の手順を順番に実行してください。

監査 — 文章を変更せずに、違反を報告します。それぞれについて、規則番号、該当箇所、準拠した書き換えを提示してください。引用する前に references/rules.md を読んでください。番号は直感的ではありません（Rule 3.1 は文の長さではなく動詞の形に関する規則です）。記憶を頼りに引用すると、自信満々に誤った参照を示すことになります。

適用レベルを選ぶ

呼び出し引数：$ARGUMENTS

引数に practical または strict が含まれていれば、それに応じて適用レベルが決まります。それ以外の内容は、対象テキストまたはそのパスとして扱います。引数が空の場合は、スキルが単独で起動されたことを意味するため、最後の列を基に依頼内容から判断してください。

適用レベル	引数で指定されていない場合の選択基準	適用内容
実用（デフォルト）	ユーザーが、より明確なドキュメントを求めている	構造に関するすべての規則。専門用語はそのままにします。idempotent、backpressure、webhook は技術用語です。
厳格	ユーザーが STE、ASD-STE100 を指定するか、準拠を求めている	構造に関する規則に加えて、語彙の規則も適用します。認定を受けた準拠には公式辞書が必要だと明確に伝えてください。このスキルにはその辞書が含まれていません。asd-ste100.org から無料で入手できます。

出力の最初の行で、選んだ適用レベルを示してください。そうすれば、ユーザーは書き換え全体を読み直さずに、ひと言で修正できます。

手順 1 — 文章を分類する

以下の各規則は、この分類に応じて適用が分かれます。まず分類を決め、文章内で2種類を混在させないでください。

項目	手順説明	説明文
目的	読者に何をすべきか伝える	何かが何であるか、または何をするか説明する
動詞の形	命令形 — 「ポッドを再起動します。」	単純現在形、過去形、または未来形
文の長さ	20語	25語
単位	1文につき1つの指示	1段落につき1つの話題、最大6文

クイックスタートは手順説明です。アーキテクチャの概要は説明文です。手順の途中にある注記は説明文として扱います。情報だけを伝え、命令形は使わず、25語の上限が適用されます。

手順 2 — 語彙を固定する

文章を書き始める前に行い、編集時には行わないでください。文書全体で、1つの概念には1つの語だけを使います。読者はその語を一度覚えれば済みます。語が変わると、読者は意味も変わったと思い、その違いを調べ始めます。

各行から1つ選び、それ以外は使わないでください。

• check / verify / confirm / validate / ensure → 1つ選びます。「Make sure that」が最も安全です。STE では check と test は名詞だからです。
• config / configuration / settings / options / preferences → 1つ選びます。
• run / execute / invoke / launch / trigger → 1つ選びます。
• show / display / render / present / surface → 1つ選びます。
• delete / remove / drop / destroy → 意味が異なる場合は意味ごとに1つ選び、それぞれを区別して使い続けます。
• 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」は、装飾の中に事実を隠しています。独立した文にしてください。

能動態を使います。受動態は、動作主が分からない説明文でのみ使えます。

動作には動詞を使って名前を付けます。動詞から作った名詞は使いません。「apply encryption to the payload」ではなく、「encrypt 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）してはいけません。複数語からなる名詞は3語までにし、それより長い連結は前置詞で区切ります。

• 変更前： the connection pool acquisition timeout value
• 変更後： the timeout for acquiring a connection from the pool

アメリカ英語のスペルを使います。単一の動詞で表せる場合は、句動詞を使いません。set up → install または configure、go down → decrease または stop とします。

句読点と文字数の数え方

セミコロン以外の標準的な句読点はすべて使えます。セミコロンの代わりに、二つの文に分けてください。括弧は、参照、略語、短い選択肢を示す場合に使えます。

文の文字数を数えるときは、次の各項目を1語として数えます。数字、単位付きの数字、略語、識別子、バッククォートまたは引用符で囲まれたもの、固有名詞、タイトル、ハイフンでつないだ語です。括弧内のテキストは、全体で1語として数えます。縦方向のリストを導入するコロンは、文字数を数える際に文の終わりとみなします。

kubectl rollout restart deployment/api は4語ではなく1語として数えます。長い識別子も文字数の上限を超える原因にはなりません。文字数を抑えるためにコマンドを短くしてはいけません。

見つけ次第、削除する

これらの表現は事実を何も伝えません。たいていの場合、言い換えるのではなく削除します。その単語が何を加えるのか説明できなければ、何も加えていません。

次の表現ではなく	次のように書く
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	「2回再試行して停止する」のように、実際の動作を書く

この作業には2つの制限があります。文の長さを抑えるために事実を削除してはいけません。代わりに文を分けてください。曖昧な形容詞を置き換えるために、数値を捏造してはいけません。測定値がない場合は形容詞を削除し、何も書かないでください。

書き換えてはいけないもの

コードブロック、インラインコード、識別子、コマンド、フラグ、パス、環境変数名、設定キー、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 節	主語を明示した新しい文にします。
;	セミコロン	2つの文に分けます。
文中の if when	命令の後に続く条件	条件を文頭に移し、コンマを付けます。
e.g. i.e. etc.	ラテン語の略語	展開するか、項目を明記します。

次に、最も長い3文の文字数を20／25文字の上限と照合し、段落が6文以内か、名詞の連なりが3語以内かを確認します。最後に、Pass 2で使用を避けた単語を検索し、見つかった箇所をすべて置き換えます。コードや引用文以外に一致箇所があれば、違反です。

作業例

変更前 — 編集前の草稿の段落：

デプロイ後のクエリが遅い場合。 デプロイ後にレイテンシーが上昇している場合は、コネクションプールが飽和していないか確認してください。これは、長時間実行されるクエリがコネクションを保持し、新しいリクエストがコネクションを取得できなくなることが原因である場合がよくあります。また、pool_max がデフォルト値（10）のままになっていないか確認してください。本番環境のワークロードには不十分な可能性があります。さらに、暴走したクエリが自動的に終了するように、ステートメントタイムアウトを有効にすることも検討してください。

変更後 — 手順として分類し、動詞を「必ず確認する」に統一し、条件を先に移動し、1文につき1つの指示にしています：

デプロイ後にクエリが遅い場合。 長時間実行されるクエリがプール内のすべてのコネクションを保持すると、レイテンシーが上昇します。そのため、新しいリクエストは空きコネクションを待つことになります。

1. プールが飽和していないことを必ず確認してください。アクティブなコネクション数を pool_max と比較します。
2. pool_max がまだ 10 の場合は、値を増やしてください。デフォルト値は本番環境には低すぎます。
3. ステートメントタイムアウトを設定してください。これにより、データベースがオペレーターを介さずに暴走したクエリを停止します。

文の長さは45語から20語未満になりました。「Checking」「verify」「ensure」は、1つの動詞に統一されました。2つの条件は、それぞれ対応する指示の前に移動しました。pool_max と 10 は変更せず、それぞれ1語として数えています。

適用されないケース

STE は意図的に説得表現を取り除くため、マーケティングページ、ローンチ投稿、ブランド向けの文章には適しません。その種の文章に適用するようユーザーから依頼された場合は、その旨を伝え、ページからリンクされているドキュメントへの適用を提案してください。

エラーメッセージ、ランブック、ポストモーテム、リリースノート、コミットメッセージ、UI 文言、エージェントへの指示、翻訳準備については、references/contexts.md をお読みください。ルールは共通ですが、出力の形式はそれぞれ異なります。

このファイルは補助資料として扱い、認証として扱わないでください。ASD および STE Maintenance Group はこのファイルとは無関係であり、文書が基準に適合することを保証できるソフトウェアはありません。商標 ASD-STE100 は ASD に帰属し、asd-ste100.org では基準を無料で提供しています。

参考資料

• references/rules.md — 番号付きの53のライティングルールです。監査でルール番号を引用する前にお読みください。
• references/contexts.md — エラーメッセージ、ランブック、インシデントレポート、リリースノート、UI 文言、エージェントへの指示、ローカライズにルールを適用する方法です。