Prompts for Explaining Technical Concepts

What Makes a Good Technical Explanation? Explaining technical concepts is one of the most valuable uses of language models for learners, educators, and teams. It is also easy to do poorly. A weak explanation is too abstract, assumes knowledge the reader lacks, uses an analogy that misleads, or is simply wrong.

A good explanation has five qualities:

Quality Meaning Calibrated Starts from what the reader already knows Concrete Uses examples, not only definitions Accurate Correct, including versions and limitations Structured Moves from simple to complex Checkable The reader can test their understanding This lesson is a practical collection of prompts that produce explanations with these qualities. They are useful for tutorials, documentation, onboarding new team members, and learning yourself.

Recipe Produces

1. Level-calibrated explanation An explanation that starts where the reader is
2. Analogy with its limits An intuitive comparison, and where it breaks down
3. Step-by-step mechanism What happens, in order, when something runs
4. Comparison of two concepts Differences that are commonly confused
5. Layered explanation One sentence, one paragraph, then technical depth
6. Correcting a misconception What is wrong, why it seems right, what is true
7. Socratic tutor Guided questions instead of answers
8. Check-your-understanding questions Questions that test application
9. Accuracy controls Versions, uncertainty, and sources Recipe 1: Level-Calibrated Explanation Use it when: explaining a concept to a specific reader.

Prompt Explain {concept} to a reader who:

• already knows: {knows}
• does not yet know: {does_not_know}
• wants to: {goal}

Structure:

1. What it is, in one or two simple sentences
2. Why it exists: the problem it solves
3. A small, concrete example
4. How it works, at the level this reader needs
5. When to use it, and when not to

Explain any technical term the first time it appears. Maximum {max_words} words. Example Settings concept: database indexes knows: basic SQL SELECT queries, Python does_not_know: how databases store and search data internally goal: understand why some Django queries are slow Why It Works What the reader knows and does not know is far more precise than "for beginners" (Lesson 34, audience). The explanation can build on SQL and avoid internal storage details that this reader does not need. The structure follows a teaching order: definition, motivation, example, mechanism, usage. Explaining why a concept exists before how it works makes the mechanism easier to understand. "Explain any technical term the first time it appears" prevents unexplained jargon. Recipe 2: Analogy With Its Limits Use it when: a concept is abstract, and an everyday comparison would make it intuitive.

Prompt Explain {concept} using one everyday analogy suitable for {audience}.

1. Describe the analogy in 2 or 3 sentences.
2. Map each part of the analogy to the real concept, as a short list.
3. Explain where the analogy breaks down: what is different in reality.
4. Give a one-sentence technical definition at the end. Example Output (Abbreviated) Analogy: A database index is like the index at the back of a textbook. Instead of reading every page to find "recursion", you look it up in the index and jump to the right pages.

Mapping:

• Book pages → rows in the table
• Index entry → indexed column value
• Page numbers → locations of the matching rows

Where it breaks down: A book index is written once, but a database must update its indexes every time data is inserted, changed, or deleted, which is why indexes make writes slower.

Definition: An index is a separate data structure that lets the database find rows by the values in certain columns without scanning the whole table. Why It Works Analogies help understanding, but every analogy is wrong somewhere. Explaining where it breaks down prevents learners from carrying a misleading idea forward. In the example, the limit of the analogy introduces a real, important trade-off: indexes slow down writes.

Recipe 3: Step-by-Step Mechanism Use it when: the learner needs to understand what happens when something runs, such as a web request, a Git merge, or a login.

Prompt Explain what happens, step by step, when {event}.

• Number each step.
• For each step, name the component involved and what it does.
• Keep each step to one or two sentences.
• After the steps, list the 2 points where things most commonly go wrong, and what a developer would see in that case.

Context: {context} Example Settings event: a user submits the login form on a Django website context: the site uses Django's built-in authentication with sessions Why It Works Numbered steps with named components turn a vague process into a clear sequence. Common failure points connect the explanation to real debugging work, which makes it immediately useful for developers. Context such as "Django's built-in authentication with sessions" prevents a generic explanation that does not match the reader's system. Recipe 4: Comparing Two Concepts Use it when: learners confuse two related ideas, such as authentication and authorization, or processes and threads.

Prompt Explain the difference between {concept_a} and {concept_b} for {audience}.

1. One sentence defining each.
2. A comparison table with rows: {dimensions}
3. One realistic example where both appear together, showing which is which.
4. The most common confusion between them, and how to remember the difference. Example Settings concept_a: authentication concept_b: authorization dimensions: Question it answers, When it happens, Example in a web app, What happens when it fails (HTTP status) Why It Works Defined comparison dimensions focus the table on differences that matter. One example containing both is especially effective: for example, logging in (authentication) and then trying to open the admin page as a normal user (authorization). The memory hint addresses the confusion directly. For accuracy, check technical details such as HTTP status codes: 401 is typically used when authentication is missing or invalid, and 403 when the user is authenticated but not allowed.

Recipe 5: Layered Explanation Use it when: readers have different levels of interest, such as in documentation, glossaries, or course pages.

Prompt Explain {concept} in three layers:

Layer 1 — One sentence: what it is, for anyone. Layer 2 — One paragraph: how it works and why it matters, for a beginner developer. Layer 3 — Technical details: important mechanics, limitations, and a short code example, for an experienced developer.

Each layer must be correct on its own; later layers add detail, they do not contradict earlier ones. Why It Works Readers stop at the layer they need. The rule that layers must not contradict each other prevents a common problem in simplified explanations, where the simple version teaches something that the detailed version later has to "unteach".

Recipe 6: Correcting a Misconception Use it when: a learner holds a common wrong belief, or when you write content to prevent one.

Prompt A learner believes: "{misconception}"

1. State clearly whether this is true, false, or partly true.
2. Explain why the belief seems reasonable.
3. Explain what is actually true, with a concrete example.
4. Give one simple test or experiment the learner can try to see it themselves.

Be respectful: do not make the learner feel foolish for holding the belief. Example Settings misconception: Using const in JavaScript makes an object impossible to change. Why It Works Explaining why the belief seems reasonable respects the learner and addresses the source of the confusion. A test the learner can run, here creating a const object and changing one of its properties, replaces trust with evidence. Learners remember what they observe. "Partly true" is often the honest answer: const prevents reassigning the variable, but it does not make the object's contents immutable. Recipe 7: Socratic Tutor The Socratic method teaches by asking questions that lead learners to reason their way to understanding, rather than giving answers directly.

Use it when: learners should work through a problem themselves, for example on graded assignments or when building problem-solving skills.

Prompt You are a patient programming tutor. The student is working on: {problem}

Rules:

• Do not give the final answer or complete code.
• Ask one guiding question at a time, based on the student's last message.
• If the student is stuck after two attempts, give a small hint, not the solution.
• When the student reaches a correct idea, confirm it and ask them to explain why it works.
• Keep each reply under 60 words. Why It Works One question at a time keeps the conversation focused. Escalating hints prevent frustration without giving away the answer. Asking the student to explain confirms real understanding rather than a lucky guess. This connects to persona design (Lesson 34): the tutor's boundaries must be explicit, because a helpful model's default is to give complete answers.

Recipe 8: Check-Your-Understanding Questions Use it when: ending an explanation, lesson, or documentation page with practice questions.

Prompt Write 4 questions that test understanding of {concept}, based on the explanation in .

• Question 1: explain the concept in your own words
• Question 2: predict what happens in a small scenario
• Question 3: find the mistake in a short example
• Question 4: decide whether to use the concept in a given situation, and why

Provide the expected answer for each question separately, after all the questions.

{explanation} Why It Works The four question types test application, not memorization: prediction, debugging, and decision-making show whether the learner can use the concept. Separating answers from questions lets learners attempt them first.

Check every expected answer, especially for prediction questions involving code: run the code to confirm.

Recipe 9: Accuracy Controls Technical explanations go out of date and can contain subtle errors. Add these controls to any explanation prompt where accuracy matters:

Accuracy rules:

• State the version this explanation applies to: {technology} {version}.
• If behavior differs between versions, say so.
• If you are not certain about a detail, say so explicitly instead of guessing.
• Do not invent function names, parameters, or commands. Use only ones you are confident exist in this version.
• At the end, list the facts a reader should verify in the official documentation. Why It Works Version statements prevent outdated syntax from being presented as current (Lesson 6). Permission to express uncertainty reduces confident errors (Lesson 10, Tip 3). A list of facts to verify makes review efficient for authors publishing explanations. For published tutorials, provide the relevant official documentation as context and restrict the explanation to it (Lesson 19), and test every code example.

Checking Readability in Code A simple automated check can flag explanations that use long sentences or technical terms without explaining them. It is a heuristic, a rough rule, not a precise measure, but it catches obvious problems before human review.

import re

def readability_report(text: str, jargon: list[str]) -> dict: """Report sentence length and jargon terms that are not followed by an explanation.""" sentences = [s for s in re.split(r"(?<=[.!?])\s+", text.strip()) if s] words = re.findall(r"[A-Za-z']+", text) average = len(words) / len(sentences) if sentences else 0 unexplained = [] for term in jargon: match = re.search(re.escape(term), text, re.IGNORECASE) if match: following = text[match.end():match.end() + 40] if not re.match(r"\s*((|,\s*(which|meaning|that is)|\s*means|\s*is a|\s*is the)", following): unexplained.append(term) return {"sentences": len(sentences), "avg_words_per_sentence": round(average, 1), "unexplained_terms": unexplained}

text = ("An API (a way for programs to talk to each other) lets your app ask another service " "for data. The server returns JSON. Your app reads the response and shows it to the user.") print(readability_report(text, ["API", "JSON", "server"])) Output:

{'sentences': 3, 'avg_words_per_sentence': 11.3, 'unexplained_terms': ['JSON', 'server']} Code Explanation Sentence splitting: the regular expression splits after ., !, or ? followed by whitespace. Average sentence length: total words divided by the number of sentences. Shorter averages are usually easier for beginners to read. Unexplained terms: for each jargon term, the code looks at the text right after its first appearance. If it is not followed by an explanation pattern, such as parentheses or "which means", the term is reported. Reading the Result "API" is explained in parentheses. "JSON" and "server" are used without explanation, so a beginner may not understand "The server returns JSON." Revise the explanation, or ask the model to explain those terms. The patterns are simple, so treat the report as a prompt for review, not a final judgment.

Common Mistakes Mistake 1: "Explain X" Without a Reader What it is: Asking for an explanation without describing the reader.

Why it happens: The concept seems to define the explanation.

What it causes: Explanations that are too basic for some readers and too advanced for others.

How to fix it: State what the reader knows, does not know, and wants to do.

Mistake 2: Analogies Without Limits What it is: Presenting an analogy as if it were exact.

Why it happens: Analogies feel complete.

What it causes: Learners carry misleading ideas into real work.

How to fix it: Always ask where the analogy breaks down.

Mistake 3: Unverified Technical Details What it is: Publishing explanations with function names, commands, or behaviors that were not checked.

Why it happens: The explanation reads confidently.

What it causes: Learners copy incorrect or outdated code.

How to fix it: State versions, allow uncertainty, provide documentation as context, and test examples.

Mistake 4: Explanations Without Practice What it is: Ending with the explanation alone.

Why it happens: The explanation feels complete.

What it causes: Learners believe they understand but cannot apply the concept.

How to fix it: Add questions that test prediction, debugging, and decisions.

Best Practices Calibrate to the reader. Describe their knowledge, gaps, and goal.

Explain why before how. Motivation makes mechanisms easier to understand.

Use concrete examples and analogies, with their limits. Intuition plus accuracy.

Structure from simple to complex. Layers that build, never contradict.

Control accuracy. Versions, uncertainty, documentation context, and tested examples.

End with active practice. Questions that require applying the concept.

Try It Yourself Exercise 1: Three Readers, One Concept Choose a concept such as caching, Git branches, or REST APIs. Use Recipe 1 for three readers: a school student, a beginner developer, and a backend developer new to your project. Compare what each explanation includes and omits.

Exercise 2: Analogy Audit Ask for analogies for three concepts using Recipe 2. For each, judge whether the "where it breaks down" section identifies the most important difference between the analogy and reality. Improve the prompt if it gives superficial limits.

Exercise 3: Readability Check Generate a beginner explanation of HTTPS with Recipe 1. Run readability_report() with a jargon list such as ["encryption", "certificate", "TLS", "server"]. Revise the explanation until no important term is unexplained and the average sentence length is below 15 words.