"I Still Don't Understand" — After the Code
The most humbling moment in explaining things is hearing "I still don't get it" after someone has seen the code and the code-level analogy. The reflex response is to re-explain with more code. It gets worse.
That recurring moment is why real-world-analogy exists in my agent-playbooks repo. Its premise: when code explanations fail to land, the missing piece is usually not more code — it's a story whose structure is the system.
It's the sibling of cross-lang-analogy, which maps language → language ("goroutines are like async/await"). This one maps system → physical world ("Redis is a desk of timed sticky notes").
A Metaphor Is Not an Analogy
The core principle of the playbook is blunt: an analogy is only as good as its mapping table.
A metaphor vibes ("the cache is like short-term memory"). An analogy has a cast list where every moving part of the real system has exactly one counterpart in the story, and every interaction in the story corresponds to a real interaction. The parts that cannot be mapped are exactly the places the analogy lies — and the playbook forces you to declare them before the learner discovers them and stops trusting you.
The Workflow
- Diagnose the gap. Capture the learner's exact question, verbatim. An analogy that answers a different question is a performance, not a lesson.
- Choose a setting whose physics matches. Cache + TTL needs objects that expire (timed sticky notes, day-old bread). An index needs a book with tabs. Rate limiting needs a bouncer.
- Build the cast — mapping table first, story second. The table is mandatory. If a row cannot preserve the system's invariant, the setting is wrong; pick another.
- Walk the scenarios — including the learner's exact question as one scene, with the work counted out loud.
- Break the analogy honestly. Name where the story stops mapping.
- Punchline + bridge back. One memorable sentence, then a list mapping every story character back to its technical name.
Watching It Work: The Station Info Desk
Concretely: a learner asks why a commuter-rail project needs Postgres and Redis — "why not just one big array we filter?" The playbook picks a station information desk (cultural proximity beats cleverness).
The cast:
- 📕 Timetable book with tab dividers → Postgres + B-tree index
- 🗒️ Sticky note with a 2-minute timer → Redis key with TTL
- 🧹 Janitor collecting expired notes → TTL eviction
- 🧑💼 Info desk clerk → the backend service
Then the scenes. Fifty passengers ask about the same line. Design A: the clerk flips through the 52-page timetable book for every single passenger — fifty times fifty pages. Design B: after the first lookup, the clerk scribbles the answer on a sticky note with a 2-minute timer; the other forty-nine passengers read the note for free. When the timer dies, the janitor bins the note, and the next asker re-consults the book once.
That is cache-aside with TTL — but now the arithmetic visibly favors the cache, and the expiry that felt arbitrary in the docs is just a sticky note that went stale.
Where does it break? The playbook says it out loud: paper is nearly free and the janitor arrives exactly on time, while real Redis keys consume memory and TTL doesn't wait for anyone. Declaring the break before the learner spots it keeps the trust intact.
The punchline sticks: "Redis stores ready answers, not raw ingredients." And the bridge-back list makes sure the learner leaves holding both vocabularies — sticky note and SET key value EX 120.
Lessons Learned
- The mapping table is the difference between an analogy and a vibe. Build it before the first sentence of the story.
- One concept per story. A second concept gets a second story; mash-ups destroy the structure.
- Count the work out loud. Analogies convince when the arithmetic is visible.
- Declare where it breaks. Every analogy lies somewhere; owning it first is cheaper than being caught.
If your explanations keep bouncing off someone, try demanding a cast list instead of another code sample. Hopefully it saves your next "I still don't get it" moment.