bpinhosilva/ste-simplify

STE Simplify

概要

ASD-STE100 簡略化技術英語 (STE) の実用的なサブセットを使用して、明確で曖昧さのない説明と指示を作成します。

核となる原則: 1 つの単語に 1 つの意味、1 つの文に 1 つの考え、能動態、単純時制。

これは STE のサブセットであり、完全な仕様ではありません。出力で ASD-STE100 準拠を主張しないでください。

スタイルが重要なクリエイティブ、マーケティング、または会話形式の散文には使用しないでください。

変更せずに保持する

以下のものを正確にコピーします。ルールは、それらの周囲の散文にのみ適用します。

• コード、コマンド、ファイルパス、引用符で囲まれた値（例: 'localhost'）
• エラーメッセージとログ文字列
• API、関数、パラメータ、変数名
• 製品名、固有名詞、バージョン番号
• 引用テキストと法的テキスト
• ドキュメントを書き換える際のマークダウン構造: 見出し、リンク、表、コードブロック。見出し、リストアイテム、表のセル内の散文は書き換えますが、同じ構造を維持します。

意味を保持する

• すべての文の動作と目的語を保持します。ソースに記載されていないアドバイス、原因、手順を追加しないでください。
• 追加してよい唯一の内容は、技術用語の 1 文による定義です（「単語」を参照）。
• 可能性を示すには、if、sometimes、probably、または may を使用します。可能性を事実に変えないでください。
• 簡単な単語が正確さを失う場合は、元の単語を保持し、それを定義します。
• ソースに奇妙な用語や誤った用語がある場合は、ソースの表現を保持します。テキストの後に Note: で始まる 1 行を追加し、問題を明記します。黙って修正しないでください。
• ソースに、前にリストがない宙ぶらりんの etc. がある場合は、それを削除します。

ルール

1. 単語

• 1 つの単語に 1 つの意味。 テキスト全体で同じものに同じ単語を使用します。ものの名前を変更しないでください。

• 簡単な単語を選びます:

  使用する語句	代わりに使用しない語句
  use	utilize, employ, leverage
  start	commence, initiate
  stop	cease, terminate, discontinue
  show	demonstrate, indicate, illustrate
  change	modify, alter
  make sure	ensure, ascertain
  help	facilitate, assist
  need, must	require, necessitate
  if	provided that, in the event that
  because	due to the fact that, since, as (理由を示す場合。since は時間を示す場合に正しい)

• 慣用句、スラング、比喩、類推は使用しません。 もの自体で説明します。

• 短縮形は使用しません。 doesn't ではなく does not と書きます。

• e.g.、i.e.、etc. の代わりに for example、that is、and so on と書きます。

• 技術用語は、初めて使用する際に 1 文で定義します（例: daemon、write-ahead log）。保存しなければならない名前は定義しないでください。

2. 名詞

• 名詞の連なりは最大 3 つまで。 より長い連なりは前置詞で分割します。
  • 悪い例: "Run the production database connection pool health check."
  • 良い例: "Check the health of the connection pool for the production database."
• 冠詞 (the、a、an) を保持します。

3. 動詞

• 能動態。 誰が、または何が動作を行うかを明記します。
  • 悪い例: "The configuration file is read by the server."
  • 良い例: "The server reads the configuration file."
• 指示には命令法。
  • 悪い例: "You should restart the service."
  • 良い例: "Restart the service."
• 単純時制。 単純現在、単純過去、単純未来 (will read) を使用します。進行形 (is reading) や完了形 (has read) は使用しません。Has と have は本動詞としては正しいです（the account has a balance）。
• 法助動詞: would、could、might は使用しません。may は可能性を示す場合にのみ使用します。can は能力を示す場合にのみ使用します。should は命令法に変更するか、動作が必須の場合は must に変更します。
  • 悪い例: "You should back up the database before the upgrade."
  • 良い例: "Back up the database before the upgrade."
• 動名詞を名詞として使用しません。 分詞を形容詞として使用するのは正しいです（the running process）。
  • 悪い例: "Logging errors helps with debugging."
  • 良い例: "Record errors in the log to help you find bugs."

4. 文と段落

• 説明: 1 文あたり最大 25 語。1 文に 1 つの考え。
• 指示: 1 文あたり最大 20 語。2 つの動作が同時に発生する場合を除き、1 文に 1 つの指示。この制限は、番号付きリストの各項目にも適用されます。
• 混合テキスト: 読者に動作を指示するすべての指示に 20 語の制限を適用します。システムの動作の説明における手順を含む、その他すべてに 25 語の制限を適用します。
• 条件を先に。
  • 悪い例: "Delete the lock file if the process stops."
  • 良い例: "If the process stops, delete the lock file."
• 1 段落あたり最大 6 文。 1 段落に 1 つのトピック。
• 3 つ以上の項目または順序のある手順には、縦方向のリストを使用します。

5. 警告

• 手順が怪我、データ損失、または損傷を引き起こす可能性がある場合は、その手順の 前に 短い Warning: 行を配置します。リスクを明記します。
• 1 つのリスクが複数の手順に適用される場合は、それらの手順の最初の前に 1 つの Warning: 行を記述します。

出力構造

概念を説明する場合（これらの見出しをこの順序で使用します。オプションのセクションは、そのルールに従って省略します）:

1. Definition (定義): 1～2 文。それが何であり、何をするのかを述べます。
2. How It Works (仕組み): 概念に順序のあるプロセスがある場合にのみ含めます。短い文の番号付きリストを使用します。
3. Key Terms (主要用語): テキスト内の、新しい読者が知らないであろう各技術用語をリストします（Definition ですでに定義されている主な用語は除く）。それぞれを 1 文で定義します。リストが空の場合はこのセクションを省略します。
4. Example (例): 具体的で最小限の例を 1 つ。最大 5 文または手順。

既存のテキストを書き換える場合: 書き換えたテキストのみを出力し、「意味を保持する」ルールで必要な場合は Note: 行を追加します。見出しは使用しません。手順には縦方向のリストを使用します。ユーザーが要求しない限り、前置きや変更点のリストは追加しないでください。

読者のレベル: ユーザーが読者は初心者または初級者であると述べた場合は、すべての技術用語を定義し、Key Terms セクションを使用します。ユーザーがレベルを指定しない場合は、読者はその分野の基礎を知っているものと想定します。分野全体ではなく、特定の概念を説明します。

例

既存のテキストの書き換え

ソース:

The deployment pipeline's artifact promotion gating mechanism is being leveraged to ensure that builds which haven't been validated by QA aren't propagated to prod.

書き換え:

The pipeline blocks builds that QA did not validate. Only validated builds go to production.

概念の説明

リクエスト: "Explain what a database index is."

Definition (定義): A database index is a data structure that helps the database find rows quickly. The database keeps the index in addition to the table.

How It Works (仕組み):

1. The database copies the values of one or more columns into the index.
2. The database sorts these values and stores a pointer to each row.
3. A query searches the sorted values instead of every row in the table.

Key Terms (主要用語):

• Column (列): One named field in each row of a table.
• Pointer (ポインタ): A value that gives the location of a row.

Example (例): A users table has one million rows. You add an index on the email column. A query for one email address now reads only a few index entries. Without the index, the query reads all one million rows.

応答前の自己チェック

ドラフトを一度読み、各違反を修正します。

• 説明が 25 語を超えている、または指示やリストの手順が 20 語を超えている場合は、分割します。
• 受動態、進行形または完了形、would/could/might、または should がある場合は、書き換えます。
• 動名詞が名詞として使用されている場合は、単純な動詞を使用します。
• 3 つを超える名詞の連なりがある場合は、of、for、in、または to を使用して分割します。
• 短縮形、慣用句、比喩、または e.g.、i.e.、etc. がある場合は、置き換えます。
• 表の「代わりに使用しない語句」の列にある単語がある場合は、「使用する語句」の列の単語を使用します。
• ソースに含まれていない事実、手順、原因がある場合は、削除します。
• 保護されたテキスト（コード、名前、エラー、引用符で囲まれた値、マークダウン構造）が変更された場合は、正確に復元します。
• 1 つのものが 2 つの名前で呼ばれている場合は、1 つに統一します。