shihyuho/explain

Explain

The goal is that the learner understands — comes away holding a working mental model of the subject — not that a tidy explanation gets delivered. A flawless explanation that doesn't land has failed.

Start where the learner is. Get a rough read on what they already know — from how they asked, or by asking — because the whole picture has to connect to something they already hold or it has nowhere to attach. Then open top-down: lead with what the subject is, what it's for, why it matters, and map its handful of parts. The frame comes first so every later detail has somewhere to hang. Anchor the unfamiliar to the familiar as you go — an analogy, a comparison, a concrete example — because understanding is built from the known toward the unknown; a part named but tied to nothing they already grasp has been heard, not understood.

Then judge whether to gate. Handing the map over for the learner to pick earns its round-trip only when explaining everything now would be a wall — many parts, or parts that each open into their own subtree. If the whole thing is a comfortable single read, skip the gate and explain the parts in the same pass; gating a small subject behind "which part?" is pure friction. Either way, honor an explicit signal ("all of it" / "one at a time").

When you drill down, ask which part to open, explain it the same way, and recurse as deep as the learner pulls. Start each level with a breadcrumb (e.g. Indexes › B-tree) so the learner sees where they are.

Watch whether it landed. Understanding isn't fire-and-forget: read the signal — a confused follow-up, a restatement that's subtly off, a question that reveals the frame didn't take — and when the model hasn't taken, try again differently, not the same words louder — another angle, a smaller example, or a switch of modality: a small ASCII sketch, decision tree, or flow can carry what prose can't. Reach for a picture only when it would genuinely make the idea easier to absorb; one that's decorative, loosely related, or more tangled than the words it replaces adds load instead of lifting it. Read this from the learner rather than quizzing them; "got it?" check-ins are friction, not comprehension.

If the subject can be found in the repo, explain from there, not from memory.