Teach-back: finding gaps by explaining

Why this matters

Reading a lesson makes its ideas feel familiar. Familiar is not the same as understood. You read the sentence "a function takes inputs and gives back a result", you nod, and the sentence sounds right. Then you open an empty file and cannot write a function, because the nod was recognition and not knowledge.

A teach-back is a way to test this. You explain a topic as if you were teaching someone who knows nothing about it. You do it without notes. Then you compare what you said with the source. The parts you could not say, or said wrongly, are your gaps. A gap is a piece of a topic you do not have yet.

The method takes about fifteen minutes for one topic. Five minutes go to explaining, five to writing down and checking, and five to filling the gap. That is less time than reading the same lesson three times, and it shows you the exact part to read again.

The next lesson in this module, "Reading official docs well", shows where to find exact facts once you know what you are missing. The reading errors lesson earlier in this module covers how to learn from an error message.

The idea, built step by step

Step 1: Choose a topic small enough for five minutes

A topic that fits in five minutes has one main idea. "Programming" is too big. "What a variable is" fits. "What a function is" fits. "How the internet works" is too big, but "what a DNS lookup is" fits.

The test is simple. Can you name the main idea in one sentence? If not, the topic is too big. Split it into two topics and do them one at a time.

Step 2: Explain with no notes

Follow these rules during the five minutes:

• Set a timer for five minutes. A phone timer is fine.
• Close the lesson, the code and every other tab.
• Imagine a friend who has never written code. Explain to that friend.
• Use one example. An example forces you to say something concrete.
• Speak out loud, or type into a blank file. Speaking finds the places where you stumble. Typing gives you a record for step 3. Either works.
• Do not stop to look things up. Write the word "unsure" in your head or on paper, mark the place, and keep going.

Here is a worked example. The topic is a function. This is what a beginner might say in five minutes:

A function is a block of code with a name. You write its name with brackets to use it. It takes some values in and gives back an answer.

Read it closely. It has three ideas. The first is correct: a function is code with a name. The second is correct too: writing the name with brackets runs the code. The third is vague. "Some values in" points at inputs without using the word. "An answer" points at a result without saying what kind of result. The speaker may understand these ideas and lack the words, or may not understand them at all. The explanation alone cannot tell which, and the next steps are how you find out.

Step 3: Write down what you said

Write the words you said, or type them. If you spoke, record a voice memo and type it up right away, or write from memory before you do anything else. Do not tidy the text before you check it. The rough version shows the gaps. A polished version hides them.

Keep the text. You will compare it with the lesson in step 4, and you will compare it again after step 5.

Step 4: Compare with the lesson and sort the gaps

Read the lesson section on the topic once, then compare it with your text. Sort each difference into one of three kinds:

• Missing. The lesson has a point you did not mention at all. Example: the function explanation above never says that a function can be called more than once, so the gap is "can be called again".
• Wrong. You said something the lesson contradicts. Example: a beginner says a function runs as soon as the file is saved. The gap is a wrong belief, and it needs correcting, not just filling in.
• Vague. You used the right idea with words that carry no meaning. Example: "some values in". The gap is the missing term and the missing example.

Missing and wrong gaps are easy to see. Vague gaps are the most common, and the easiest to miss, because the sentence sounds fine. Test every vague sentence with one question: can I give a concrete example of it? If you cannot, the sentence is a gap.

Step 5: Fill the gap and explain it again

Re-read only the part that matches each gap. Do not re-read the whole lesson. Then explain that part again, with no notes, in your own words and with one example.

Stop when you can explain every part of the topic once in a row, without looking anything up. Then write the new version and compare it with the old one. The difference between the two texts is what you learned.

A keyword check for your written explanation

Sorting gaps by hand works well, but it is slow the first few times. A short script can give a first pass. It does not understand English. It looks for words from a list. You decide what the words are.

Save this as gap_check.py:

# gap_check.py: compares a written explanation with the key points of a topic.
key_points = {
    "named block of code": ["named", "name"],
    "can be called again": ["call", "again", "reuse"],
    "takes inputs": ["input", "argument", "parameter"],
    "gives back a result": ["return", "result", "output", "gives back"],
}
 
explanation = """A function is a block of code with a name.
You write its name with brackets to use it.
It takes some values in and gives back an answer."""
 
text = explanation.lower()
covered = 0
for point, words in key_points.items():
    hits = [w for w in words if w in text]
    if hits:
        covered += 1
        print(f"covered  {point}  (matched: {', '.join(hits)})")
    else:
        print(f"GAP      {point}")
 
print(f"{covered} of {len(key_points)} key points covered")

Read the structure before you run it. key_points is a table. Each key is a point the topic must cover. Each value is a list of words that count as covering that point. explanation is the text you wrote. The loop checks each point, prints one line for it, and counts the points with at least one matching word.

Run it:

python3 gap_check.py

Output:

covered  named block of code  (matched: name)
GAP      can be called again
GAP      takes inputs
covered  gives back a result  (matched: gives back)
2 of 4 key points covered

Two lines say GAP. Look at each one by hand. For "can be called again", the speaker never says the function can run more than once, so the gap is real. For "takes inputs", the speaker did describe inputs with "takes some values in", so the GAP is a false alarm caused by the word list. The script found the first gap and missed that the second point was covered in other words.

So a GAP line tells you where to look, not what is true. Use the output as a list of places to check in step 4. Never use the count as a score.

Worked example two: a for loop

The topic is a for loop. A for loop repeats a block of code once for each item in a list. Here is a short program that uses one:

total = 0
for n in [1, 2, 3]:
    total = total + n
print(total)

Save the program as loop_sum.py and run it:

python3 loop_sum.py

Output:

6

Now the five-minute explanation, written as it might come out: "A for loop goes through a list one item at a time. For each item it runs the same lines. Here it adds each number to total, so the total is 6."

Compare it with the program. The loop-over-items part is correct. The "same lines for each item" part is correct. The result is correct. Two things are missing. The explanation does not say what n holds at each step, which is 1, then 2, then 3. It also does not say why total = 0 is above the loop. That line is the gap that matters most, because it is easy to skip and the program fails without it.

Test the gap. Save a copy without the first line as loop_no_total.py and run it:

python3 loop_no_total.py

Output:

Traceback (most recent call last):
  File "/home/chiranjeet/dev/anisha/scratch-offtmp/claude-review-06/loop_no_total.py", line 2, in <module>
    total = total + n
            ^^^^^
NameError: name 'total' is not defined

The first line of the traceback shows the full path of the file, so your path will differ. The error shows that total must exist before the loop uses it. The gap is now a fact you can point to. The next explanation should say that the starting value must be set first.

Worked example three: a topic outside code

Teach-back works for any topic, including ones with no program to run. Take git commit. Git is a tool that keeps a history of the changes in a project. A commit is one saved point in that history.

A beginner's five-minute explanation: "A commit saves my changes to git with a message."

Compare it with what the topic needs. The explanation has the main idea and a message, which is correct. The word "saves" is vague. Saves into what, and what is kept? A better version says that a commit records a snapshot of the changes that were staged, and that the commit gets its own ID. The explanation is also missing the step before a commit, which is staging: choosing which changes go into the next commit. A learner who skips staging will be confused the first time a commit contains fewer changes than they expected.

The gaps are "what kind of thing a commit records", "what staging is" and "what the ID is for". Each one can be checked against the git lesson in this course. Each one can also be turned into a single question you can answer in one sentence. That is what makes this method work: each gap becomes a question with an answer you can verify.

Common mistakes

Looking at notes during the five minutes. The explanation becomes a copy of the notes, and the gaps stay hidden. Close everything before the timer starts. If you must check something, stop the timer, check it, and start again from the beginning.

Choosing a topic that is too big. A big topic gets five minutes of partial explanation. You skip the parts you find hard, and skipped parts do not feel like gaps. They feel like the end of the topic. Split the topic and explain one piece.

Counting recognition as understanding. A common thought is "I know this, I just cannot say it right now." If you cannot say it, you cannot use it when you write code. Treat it as a gap.

Trusting the keyword check. The script from this lesson can report a point as covered when the words match for the wrong reason. Here is the same script run on a weaker explanation:

explanation = """A function is a block of code.
The name is important for the team.
It takes some values in and gives back an answer."""

Output:

covered  named block of code  (matched: name)
GAP      can be called again
GAP      takes inputs
covered  gives back a result  (matched: gives back)
2 of 4 key points covered

The first line is wrong. The sentence "The name is important for the team" uses the word "name", but it says nothing about a function having a name. The script counted it as covered. Always read the sentence that matched before you accept a covered line.

Stopping after one pass. Finding gaps is only half the method. If you do not explain the topic again, the gaps stay where they were. Do a second five-minute explanation after you fill the gaps. The second attempt should be cleaner, and if it is not, the same gap is still there.

Re-reading instead of explaining. Re-reading feels productive because the text looks familiar. It is the same trap as the first nod. Write or speak the explanation, even when the reading seems to make sense.

Practice

Exercise 1. Choose the topic "what a variable is". Set a five-minute timer and explain it with no notes. Write down what you said, then list at least three gaps. Label each gap as missing, wrong or vague.

Show the answer

Your answer should have three or more labelled gaps, each one backed by a sentence you wrote. A sample: "I said a variable holds a value. Missing: I did not say that a variable has a name you use to read it later. Vague: I wrote 'stores stuff', which is not a concrete example. Wrong: I said a variable can only hold numbers, and it can hold text too." There is no single correct list. The check is that each gap points to a sentence in your text.

Exercise 2. Open gap_check.py and add the sentence "You can call it again later." after the first line of explanation. Before you run it, predict the last line of the output. Then run it.

Show the answer

The script now reports 3 of 4 key points covered. The added sentence contains "call" and "again", so "can be called again" is covered. "takes inputs" is still a GAP, because the explanation does not use an input word. Output:

covered  named block of code  (matched: name)
covered  can be called again  (matched: call, again)
GAP      takes inputs
covered  gives back a result  (matched: gives back)
3 of 4 key points covered

Exercise 3. Remove the line total = 0 from the for loop program in this lesson. Run it and read the error. Then explain in one sentence what the error means.

Show the answer

The error is NameError: name 'total' is not defined. The program adds n to total before total has ever been given a value. The one-sentence meaning: a name has to be set before the program reads it. Put total = 0 back above the loop, and the output is 6 again.

Exercise 4. Explain the for loop program with no notes, and make sure your explanation says what n holds on each pass through the loop. Then check your text against the answer below.

Show the answer

On the first pass n is 1, on the second pass it is 2, and on the third pass it is 3. The total goes 0, then 1, then 3, then 6. If your explanation says "n goes through the list" without giving the values, it is vague. Add the three values and the running total to fix it.

Exercise 5. Write a key_points table for the topic "what a commit is". Use four points and at least three words for each point. Explain why "id" is a poor word to use in the list.

Show the answer

A sample table:

key_points = {
    "snapshot of staged changes": ["snapshot", "staged", "staging"],
    "has a message": ["message"],
    "has its own ID": ["commit id", "hash", "identifier"],
    "adds one entry to history": ["history", "one more", "new entry"],
}

The word "id" is poor because the check uses the in operator, which finds "id" inside other words such as "idea" and "did". Matches like that count as covered even when the point is missing. Longer phrases such as "commit id" avoid most of those false matches.

Summary

• A teach-back is five minutes of explaining with no notes, then a check against the lesson.
• Sort every gap into one of three kinds: missing, wrong or vague.
• A vague sentence is a gap until you can give a concrete example of it.
• The keyword script finds word matches, not understanding, so read each matched sentence before you trust it.
• Fill only the gap you found, then explain the whole topic again.