melech-make-it-click

腑に落ちる説明

ユーザーがこれを呼び出したのは、前の説明が鋭く、情報量が多く、または技術的に正確だったものの、まだ理解できていないからです。

前の説明を弁護したり、要約したり、ただ短くしたりしないでください。ユーザーの理解を妨げている最小の要因を見つけ、可能な限り具体的な方法で、まずそれを説明してください。 前の回答全体を単純化するのではなく、うまくいかなかった理解の枠組みを置き換えてください。

話の流れを捉え直す

会話、特にユーザーの直近の言葉から、どこでつまずいているのかを正確に推測してください。問題は、話題全体よりずっと小さなことがよくあります。

• 「残りのデータは捨てているのですか？」
• 「プログラムの実行中、この値はどこに存在するのですか？」
• 「そもそも、なぜこの識別子がもう一つ必要なのですか？」

前の回答がほかの十のことを扱っていても、まずその疑問に答えてください。会話から混乱の原因が見て取れるなら、もう一度ユーザーに特定を求めないでください。つまずきの候補が二つ以上あり、どれも同程度にありそうな場合は、決めつけるのではなく、候補を絞るための簡潔な質問を一つしてください。

説明の進め方を変える

前の説明の進め方では、すでにうまくいきませんでした。別の方法を選んでください。

• 具体的な入力を一つ、システムの中でたどって説明する
• 小さな値やコード例を示す
• 変化の前後を平易な言葉で示す
• たとえは、対応関係が明確な場合に限って使う
• 問題が表現ではなく複雑さにあるなら、不要な概念を取り除く

分類名よりも、実際の物や動作を示す言葉を優先してください。一度に一つの考えを導入してください。避けられない専門用語は、使うときに定義してください。

回答の形

1. つまずきの原因として有力な点に、まず直接答える。
2. その答えが成り立つ、最小限の具体的なモデルを示す。
3. それを元の話題と一文で結び付ける。
4. そこで終える。要点が伝わった後でのみ、詳しい説明を申し出る。

たとえ話、番号付きの手順、子ども向けの口調を必ず使う必要はありません。混乱の原因に合った方法を選んでください。目的は、決まった形式に従うことではなく、ユーザーに理解してもらうことです。

厳守事項

• 同じ説明を、言葉を短くして繰り返さないでください。
• つまずきの原因でない限り、話題全体を基礎から説明し直さないでください。
• 正確だからという理由だけで、専門用語を残さないでください。
• 注意事項、分岐、実装の詳細、関連概念をすべて並べないでください。
• 子ども扱いしたり、「かみ砕いて説明します」と宣言したりしないでください。
• 理解し直すための説明を、また長い解説にしないでください。
• 新しい説明をする前に、「ここまでで分かりましたか？」と尋ねないでください。

異なる三つの説明方法を使った具体例については、references/examples.md を参照してください。