simple-english

シンプルな英語

専門分野の外にいる知識のある読者が、一度読んだだけで理解できる平易な英語を書いてください。ルールの出典は、航空宇宙業界が保守マニュアルに使用する制御言語、ASD-STE100です。文書と、チャットで入力する返信では、異なるルールセットを使います。それぞれの短いルールセットを以下に示します。

文書

ドキュメントの執筆や書き直しを依頼されたときは、本文に次のルールを適用してください。

1. 各文章の種類を分類してください。手順を示す文章は、読み手に何をするかを伝えます。命令形を使い、1文を20語以内にし、1文につき指示を1つにしてください。説明文は内容を説明します。単純時制を使い、1文を25語以内にし、段落ごとにトピックを1つにまとめ、段落は最大6文にしてください。
2. コード、識別子、コマンド、フラグ、ファイルパス、引用されたエラーメッセージ、製品名、事実には手を加えないでください。元の文章に数値や原因が示されていない場合は、一般的な表現を維持してください。
3. 条件を指示より先に置き、コンマで区切ってください。「ビルドに失敗した場合は、ログを読んでください。」
4. 単純時制と能動態を使ってください。現在完了形（「has completed」→「completed」）は使わないでください。コンマの後に「-ing」形の動詞を続けないでください（「, making it easy」→新しい文にする）。行為者を明記してください。「移行を実行します。」
5. 助動詞は can、will、must を使ってください。should、would、may、might、could は使わないでください。必須を表す「should」は「must」に置き換えます。任意を表すものは削除します。
6. 文法的に完全な文にしてください。短縮形は使わず、冠詞と「that」は省略しないでください。電文調ではなく、短い文を書いてください。
7. セミコロンとエムダッシュは使わないでください。2つの文にするか、関係性を明記してください。
8. 文書全体で、1つの単語には1つの意味だけを持たせてください。check、verify、confirm、validate、ensure の代わりに make sure that を使ってください。config、settings、options の代わりに configuration を使ってください。3語を超える名詞の連なりは、前置詞を使って分けてください（「the timeout value for the connection pool」）。
9. 読み手が必要とする用語や事実は、その手順より前に示してください。概念用語は初出時に10語以内で定義し、1文につき1つだけにしてください。製品名、標準名（Postgres、S3、HTTP）、または文書の対象となるツールは定義しないでください。また、コマンドが依存するホスト、フラグ、または前の手順も明記してください。「サービスを再起動します」は「ジョブを実行するホスト上の sync サービスを再起動します」とします。
10. 重要性ではなく、事実を述べてください。事実を伝えない語句は削除してください。例：simply、seamlessly、robust、powerful、comprehensive、leverage、crucial、「in order to」、「it is worth noting」。「XだけでなくYでもある」という表現は使わないでください。装飾的な3項表現も使わないでください。「結論として」も使わないでください。
11. 書式は構造を示す場合にのみ使ってください。太字の導入句、強調のための太字、絵文字は使わないでください。見出しは2文を超えないようにしてください。縦並びのリストは、並列する項目や手順が3つ以上ある場合に使います。導入文の後にコロンを付け、各項目の先頭は大文字にし、1項目につき指示を1つにしてください。
12. 警告では、まずコマンドまたは条件を示し、その後にリスクを述べてください。「本番環境に対してこのコマンドを実行しないでください。このコマンドは行を削除します。」

アメリカ英語のスペルを使ってください。よく使われる語句を平易な表現に置き換える方法は、references/word-swaps.md に記載されています。エラーメッセージ、ランブック、インシデントレポート、リリースノート、コミットメッセージ、またはUIの文言を書く場合は、先に references/use-cases.md を読んでください。用途ごとのモードとパターンが記載されています。

変更前（AIの出力）：

接続タイムアウト。 sqlpipe が停止するか、dial tcp: i/o timeout で失敗する場合は、sqlpipe を実行しているホストが Postgres のポートに接続できることを確認してください（通常は5432です）。接続をブロックするセキュリティグループやファイアウォールのルールが原因であることがよくあります。マネージドデータベース（RDS、Cloud SQL など）に接続している場合は、インスタンスが sqlpipe のIPアドレスからの接続を許可していることを確認してください。

変更後（手順形式、見出し付き、番号付き）：

接続タイムアウト

Postgres のポート（デフォルトは5432）に接続できない場合、sqlpipe は dial tcp: i/o timeout で停止します。

1. sqlpipe を実行しているホストが Postgres のポートに接続できることを確認してください。通常、ファイアウォールまたはセキュリティグループが接続をブロックします。
2. データベースがマネージド型の場合（RDS、Cloud SQL）、インスタンスが sqlpipe のIPアドレスからの接続を受け入れることを確認してください。

返信

すべてのモードで、チャットへの返信は次のルールに従います。

1. 文章で回答します。見出し、箇条書き、太字、表は使いません。読者がコピーする必要がある場合は、コードブロックを使用できます。
2. 最初の文で回答または結果を示します。質問を言い換えて繰り返しません。
3. ダッシュ記号は使いません。関係性を示す言葉（「なぜなら」「しかし」「たとえば」など）を使うか、2つの文に分けます。
4. 概念用語は、初めて使うときに数語で定義します。「冪等（2回実行しても安全）」のようにします。製品名は定義しません。
5. 短縮形は使いません。書き出しの定型句（「もちろんです」「よい質問です」など）や締めの定型句（「お役に立てば幸いです」「お知らせください」など）も使いません。
6. 引用されたエラーテキスト、セキュリティ警告、破壊的な操作を実行する前の確認文は短縮しません。

修正前：ポッドの入れ替わり中にコントロールプレーンのリーダー選出が発生したことが原因です。心配はいりません！ 修正後：ポッドが再起動し、キューは一時的にリーダーを失いました。何もせずに復旧しました。何もする必要はありません。

提出前のセルフチェック

1. 返信：—、**、#、および - で始まる行を検索します。それぞれ削除します。
2. ドキュメント：最も長い3つの文の語数を数えます。20語または25語を超える場合は、文を分けます。'、has been、should、may、;、—、, making、**、check、verify、config、および3文に満たない見出しを検索します。見つかった箇所をすべて修正します。各手順を読み、ホスト、フラグ、または読者が事前に知っている必要のある手順が明示されているか確認します。明示されていない場合は、追加するか、該当箇所を示します。

モード

Plain がデフォルトで、上記のすべてが適用されます。ユーザーが STE、ASD-STE100、またはコンプライアンスを指定した場合は Strict が適用されます。ドキュメントを作成する前に references/strict-vocabulary.md を読み、コンプライアンスを保証するツールはないことを一度伝えます。どのモードでも、返信には Plain が適用されます。

文章の作成ではなくテキストの CHECK を求められた場合は、最初に references/rule-catalog.md を開きます。その後、違反ごとに次の形式で報告します：そのファイルから引用したルール番号、該当するテキスト、ルールに準拠した書き換え。記憶を頼りにルール番号を引用してはいけません。コンプライアンスを求められた場合は、最後に「ASD-STE100への準拠を保証するツールはありません。規格は asd-ste100.org から無料でダウンロードできます。」という文を付けます。

制限事項

これらのルールは事実や手順を対象としたものであり、説得力を損なうため、マーケティングコピーやブランド文章には適しません。その旨を伝え、ドキュメント向けに使うことを提案します。

参考資料

• references/rule-catalog.md：CHECK モード向けの、ソフトウェアの例を含む Issue 9 の53項目のルール
• references/strict-vocabulary.md：Strict モードでの辞書の運用ルール
• references/word-swaps.md：多用される単語を平易な表現に置き換えるための対応表
• references/use-cases.md：エラーメッセージ、ランブック、インシデントレポート、リリースノート、コミット、エージェントプロンプト、UI コピー、翻訳準備におけるモードとパターン