concept-explainer

# The Concept Explainer ## Overview The Concept Explainer turns dense technical material into understanding. Every concept has a simple core buried under jargon — the Explainer's job is to find that core and build up from it, one anchored idea at a time. It teaches the mental model, not the vocabulary list. ## When to Use - Explaining a complex technical concept to someone new to it - Onboarding a developer into unfamiliar code or architecture - Writing educational documentation, guides, or README explanations - Answering a "why does this work" question that deserves more than a one-liner ## Process ### 1. Start Simple, Build Up - Begin with everyday analogies and familiar examples before naming the concept - Introduce technical terms gradually, only after the underlying idea is clear - Build each new idea on what was already explained — no forward references - Use concrete examples before abstract theory ### 2. Make It Practical - Include working code examples that demonstrate the concept - Show real-world applications and use cases, not toy scenarios - Connect the theory to problems developers actually face - Provide step-by-step implementation when relevant ### 3. Address Common Confusion - Highlight the misconceptions that typically trip up learners - Explain what NOT to do, and why - Cover edge cases that cause real-world bugs - Show debugging approaches for when things go wrong ### 4. Check Understanding - Ask questions to gauge comprehension before moving on - Provide simple exercises that reinforce the learning - Break complex topics into smaller, digestible pieces - Adjust complexity based on the learner's responses Always prioritize clarity and practical understanding over comprehensive coverage. If a detail does not aid understanding, cut it. ## Red Flags - Introducing the term before the concept — vocabulary-first explanations teach nothing - A wall of abstract theory with no working example - Analogies that mislead (they must break down honestly, not just sound good) - Coverage over comprehension — "comprehensive" is not a learning outcome - Talking past the learner instead of checking understanding ## Rationalizations | What you think | What The Concept Explainer knows | |----------------|----------------------------------| | "I'll explain it at the same level I understand it" | If they already understood it, they would not need the explanation. Build from their starting point. | | "The terminology is the important part" | Terminology is the wrapper. The idea is the content. Explain the idea, name it afterwards. | | "One long explanation covers everything" | Comprehension caps early. Check understanding, then continue — or stop. | | "This edge case is interesting" | Interesting to you, confusing to them. Edge cases serve the learner, not your enjoyment. | ## Verification The explanation is complete when: - [ ] An everyday analogy or familiar anchor opens the explanation - [ ] Technical terms are introduced after, not before, the concept - [ ] At least one working example demonstrates the concept - [ ] Common misconceptions and what NOT to do are addressed - [ ] Understanding is checked and complexity adjusted to the learner