簡潔説明スキル (SES)
最初に答えを、平易な言葉で伝えてください。読者が読み飛ばせる深さの層を追加してください。真実を犠牲にしてシンプルさを取らないでください。
構造：答え、仕組み、詳細
説明は、自分が学んだ順序ではなく、読者が必要とする順序で構成します。
- 答え。 質問に直接答え、要点を述べる、平易な一文または二文。ここで読み終わる読者も、正しい全体像を持てます — 小さな全体像であり、間違った全体像ではありません。
- 仕組みと理由。 答えの背後にあるメカニズム：原因、構造、機能しているルール。
- 詳細。 数値、パラメータ、エッジケース、例外、証明。ほとんどの読者は読み飛ばす部分 — しかし、後で確認しに来た読者のために、そこに存在しなければならない部分。
以下のルールで構造を維持します。
- 各層を完了してから次の層を開始します。要約と詳細を決して混在させないでください。
- 層を見やすく、読み飛ばせるようにします：段落区切り、太字のリード、ラベル、見出し、またはメディアが対応している場合は展開可能な要素を使用します。
- 答えを変える注意事項は、答えの隣に配置します。安全性リスク、データ損失、破壊的変更、実際のコストは、決して下位層に置かないでください。
- 手順は依存関係の順序で配置します。手順の周りに散文をレイヤーします — 結果と前提条件を最初に、次に番号付き手順、最後に失敗ケース — しかし、手順を重要度で並べ替えることは絶対にしないでください。
- 深さは質問に従います。チャットの返信では一層で十分かもしれませんが、設計ドキュメントでは四層必要かもしれません。構造を埋めるために説明を水増ししないでください。
言葉遣い
- 動作主と動詞を先頭に置きます：「キャッシュは古いデータを返す」 — 「古いデータが返される可能性がある」ではありません。
- 一つのものには一つの名前を、毎回同じ名前を使います。名前を変えると、別のものとして読まれます。
- 短く一般的な単語を選びます：利用する、開始する、手助けする、表示する — ではなく、使う、始める、助ける、見せる。
- 一文に一つのアイデアを入れます。20語を上限とし、節を積み重ねるよりも分割します。
- 条件を行動の前に置きます：「ビルドが失敗したら、ロックファイルを確認する」 — 逆の順序ではありません。
- 用語は、読者が遭遇した時点で、半文で定義します。背景情報を先にまとめて詰め込まないでください。
- 抽象名詞を動詞に戻します：「ログを分析する」 — 「ログの分析を実行する」ではありません。
- フィラー、強調語、空虚な賛辞を削除します：非常に、堅牢な、シームレスな、強力な、包括的な、「重要な点として注意すべきは」。
- 形容詞の代わりに数値を示します：「40秒から6秒へ」は「劇的に高速化」よりも優れています。
基本：シンプルであっても、正確さを決して犠牲にしない
- すべての事実、数値、警告、注意事項を保持します。簡素化は詳細を下位層に移動することであり、決して削除することではありません。
- 情報源にない例、証拠、確信をでっち上げないでください。何かが不明な場合は、そのことを率直に述べてください。
- アナロジーは橋渡しであり、証明ではないと扱います。読者がそれに依存する場合は、どこで破綻するかを述べてください。
- シンプルさと正確さが衝突する場合、正確さが優先されます — その後、正確なバージョンをシンプルにする努力を続けてください。
例
改善前 — 真実で、完全だが、使いにくい：
トランザクションとは、一連のステートメントを一つの分割不可能な作業単位として扱うものであり — 最初のステートメントで暗黙的に開始され、COMMITまたはROLLBACKで終了する — 多くのマルチステップ操作はアトミックに実行された場合にのみ正しいため、重要な概念です。
改善後 — 同じ事実を、層状に：
トランザクションとは、すべて成功するか、すべて失敗するかのグループです。
最初のステートメントで開始され、
COMMIT（変更を保持）またはROLLBACK（変更を元に戻す）で終了します。グループ化が重要なのは、一部の操作は全体としてのみ正しいからです：一方の口座から引き落とし、他方の口座に入金しない転送では、資金が消失してしまいます。
配信前のチェックリスト
- 最初の文は質問に答えていますか？
- 読者はどの層で読み終えても、正しいままですか？
- 警告や答えを変える注意事項は最上位層にありますか？
- より短く、より一般的な単語で意味を保てる箇所はありませんか？
- すべての事実、数値、注意事項は保持されていますか？