How to talk about code for understanding

You’ve nailed your title, summary, and code example. Now it’s time to figure out what you’re going to say.

The “instructor” title can feel daunting. Don’t let it! If you’ve ever shown someone how to do something, you’re an experienced instructor.

Speak to support the code

In your lesson, you should show first (with your code) then maybe explain (with your voice). Your narration is quite simply the explanation of the changes you’re making to your code as you take it from its start state to its finished state.

You won’t be asking questions that teachers typically do, like “What themes can we draw from this?” You will simply relay information, explain how and why you did what, and let the learners soak it in. Keep it simple and focused on the code.

Write a script or outline

Your narration should sound casual but informed, like you’re showing something to a coworker. Some instructors find it helpful to write out a script beforehand so they’re never in doubt of what to say. It’s a great way to cut the “umm”s and “uhh”s and make your explanation as tight as possible.

If you’d rather sound more conversational, less scripted, write out an outline. We’re talking bullet points—the keywords you want to say, the points you want to hit. This approach may require you to edit a few seconds of dead air here and there, but the published narration will sound polished.

Do a dress rehearsal

Have you ever conducted a workshop? Talked at a conference? Presented to your sixth grade class? You know how essential it is to practice your talk before showtime.

Same with egghead lessons. Before you hit record, explain your code example to yourself. Out loud. Enunciate! Be confident! Believe you’re the most qualified instructor in the history of egghead!

You’ll probably trip over your words. You might realize you know how to do something but not how to articulate it. That’s okay—write notes to yourself and put your knowledge into words.

When it’s time to record, you’ll be more than ready.

Speak concisely

By now, you know the drill: egghead lessons are short and to the point. That goes for the videos, which should be 1–10 minutes long. It also goes for your narration. Less is more.

Consider this example:

Hello! Before we get started using Webpack you are going to need to install node. We are going to visit this URL and find the link to install it. Now we press "download" and we should get a file. We can now open that file and extract its contents. Now that node is installed, we can use npm to install webpack globally. Great. Now that webpack is installed globally, we can use it! Open up Sublime or your favorite editor to start working on the config.

Holy backstory! If you think back to our cheesecake-stuffed cookie cake example, we don't have to explain or justify each step in the instruction. We can assume we’re delivering content to smart, capable humans who can fill in some blanks. We have to. There’s instructing to do, and the clock is ticking.

Without the over-instruction, we have a much more concise, energetic start to the lesson.

We've got node already installed. Use npm to install webpack. Now run init and open the config to edit it.

Note how active those sentences are: install webpack. Run init. Open the config. Those are instructions.

How much personality can we bring to our lessons?

Bring all your charm and favorite idioms to your narration as long as they support your code example. That’s what egghead learners come to see: good code. Use the “show your work” trick to determine if you should talk less, code more.

The “show your work” trick

egghead lessons are concise by definition, but there’s another reason to keep your lessons sharply defined.

Too many ideas in one lesson means you’re glossing over concepts. Let’s say you mention “condition X could crash your app” because you want to cover your bases, yet you don’t take the time to really get into that subject. All you’ve accomplished is alarming your audience without giving them any solution.

Show, don’t tell

Show your work! You probably heard this when your high school math teacher forced you to write out the steps to a solution to get full credit for your answer.

It applies to coding instruction, too. The simple act of typing something out, highlighting a block with your mouse, or logging something in the console makes concepts infinitely more approachable.

If a user sees you walk through those steps, they gain confidence that they can do it, too. If they only hear you talking about concepts, they can’t readily tie the concepts back to the code. Worse yet, they might stop paying attention altogether.

Watch on mute

Here’s the trick: Turn off your audio and watch your lesson without sound.

It should be obvious from the visuals what you’re teaching. You may notice periods of 5+ seconds where nothing is happening. “Nothing” usually means you’re getting off-topic and thought it would be tough to show what you’re talking about. When you catch a section of “nothing,” write down the topic you weren’t showing. Save it for another lesson!

With this one trick, you’ll quickly turn one lesson with a lot of tangents into a focused, concise lesson about one topic. Or if you’re interested in creating a workshop, those tangents could each be a separate lesson.