Teaching DevelopersBy Geoffrey Grosenbach
The only thing more difficult than learning something new is teaching it.
Here’s some of what we’ve learned about explaining technical topics to developers.
- Teach one thing at a time
- Tell a story
- Use appropriate terminology
- Know your audience
The goal of any tutorial is to get back into the mind of someone who doesn’t understand the topic. If an explanation only makes sense to people who already know what you know, then it’s not a very good explanation.
But that insight alone doesn’t tell you how to explain well. Instead, it might help to think about how developers go wrong when trying to explain a concept.
- They try to teach too many things at once. This overwhelms the student.
- They are disorganized. Teaching things out of order makes the student do too much work to sort it out in their mind.
- They use the wrong words. Throwing an unknown term into an explanation can intimidate a student or even cause fear.
- They don’t know who they are speaking to. I don’t know of any single explanation that works for all people at all levels of learning. When developers are unclear about their audience, they risk delivering ideas that will confuse everyone listening.
Here are four solutions to these problems.
Teach one thing at a time
This is the biggest problem I see, and it’s the first strategy you should use to improve your explanations.
Decide what you’re trying to teach, and only talk about that. You’ll have to intentionally block out the 10 other things you want to communicate. If a concept is important enough, dedicate a separate chapter, slide, or day to it. Then focus on the one thing you’re trying to teach right now.
This is extremely difficult for developers. We love details. We love to debate some tiny nuance of a program before it even runs. We like discovering edge cases that no one else has thought about.
And we’re afraid. We’re afraid that when we conclude a presentation, one person in the audience will be able to say “Hah! You forgot to mention X!” Or “You were wrong on this one point!”
To teach well, you need to get over these fears. You need to allow yourself to say something that’s 99% true, even if you know someone will correct you for the 1%. Because mentioning that 1% in your explanation will probably hinder you from sticking to teaching just one thing at a time.
To teach well, you need to abandon your insurance policy of saying “We’ll cover this other thing later.” That disclaimer is only there to comfort you, not to help the student. Teach the one thing you’re trying to teach now, then teach one other thing later when you’ve finished teaching the one thing you’re teaching now.
In fact, leaving out an important concept or saying something that’s only 99% true can be used to your advantage. It can help you tell a story.
Tell a story with problems and solutions
Stories are great because they hold our attention. The story could go anywhere, but we also have a hunch about what will happen next. That anticipation keeps our interest: “Will it turn out like I think it will, or will something unexpected happen?”
Malcolm Gladwell is a great storyteller. Many of his stories use problems as a way to hold attention and lead to a solution (or continue the cycle with another problem and another solution).
A person figured this thing out. But then they discovered they were partly wrong. And it gave them a new insight into how it really worked. So they applied that knowledge to something else. And then…
When explaining a technical concept, start with a partial explanation that’s easy to understand. In order to make it understandable, you might have to leave out some details. But filling in those details now becomes the next part of your story.
Solution: Fixtures are Rails’ built-in way for feeding data to your tests. They are a concise way to describe all the data your application needs.
Problem: But fixtures become difficult to maintain when you have many different pieces of data.
Solution: It turns out they aren’t the only way. There are also factories. Here’s how factories work…
Problem: But there’s a problem with factories…
So teach one concept at a time. If you have to leave out a glaring edge case or alternate option, use it to organize your thoughts into problems and solutions that lead from one to the other.
When you’re telling a story, you need to use words. But be careful what words you use…
Beware of Terminology
In every hobby, field of study, or domain, a set of words emerges.
Mountain bikers want to grin while flowing through chunder. Skateboarders are stoked about gnar. Philosophers try not to equivocate about their ideology. Agile developers want to be clean while they keep their objects dry.
These words—big and small—are shortcuts. They make it easy for experts to discuss advanced topics after they already understand the basics.
If you are teaching experts about advanced topics, then you should use these shortcut words.But if you are teaching people who are not experts, then using domain-specific language will confuse them.
For any term, one’s relationship to the word falls under one of these categories:
- I have never heard it before, and have no idea what it means.
- I have heard it a few times but don’t understand it.
- I have a basic understanding of the word.
- I have thorough understanding. It’s part of my vocabulary. I can use it to explain other concepts.
Part of your job as a teacher is to help students add new words to their vocabulary. Finding their place in the list above will help you know which words to teach, and which ones to use.
Know your audience
Finally, understand your audience. I’m mentioning it last, but it should happen first in your preparations. Are you teaching beginners or experts? Backend programmers or front-end? People with a computer science degree or the self-taught?
This determines what terms you can use. Your professional audience will be frustrated if you spend large amounts of time explaining things they already know. Your beginner audience will be confused if you assume they are fluent in concepts they have never heard about.
This is the first part of your preparations for teaching, but is also the most uncertain. The people who show up for your presentation or consume your material online might not be the audience you prepared it for.
There is a massive need for great explanations on all kinds of topics. Without good explanations, many open source projects will fail. It’s pretty simple: if people don’t know to use your software, they won’t.
So teach one thing at a time that flows from one idea to another with the appropriate words for the intended audience.