Eloquent Explanations

by Joe Sak

Rubynation Mayan LogoThis article is the second part in a series of RubyNation Recaps. The first part was Cannibalize Yourself, and the introductory post contains a list of all the articles posted and coming up.

Five Ways to Make Your Explanations Stick

by Russ Olsen

Russ Olsen (@russolsen) likes to think that technology is there to solve problems for people, not the other way around. Russ started his career doing that other kind of engineering, the sort that involves electricity, gears and getting dirty. Pretty rapidly the wonder of computer programming lured Russ away, which probably explains why most of his fingers are still intact today.

The only limitations we really have are the ideas in our heads.

Explaining things is the way we move forward.

This is about the everyday, hallway conversations, not just a conference talk.

5. Take Explaining Seriously

We don't realize that explaining is a big part of our jobs, so we kind of blow it off. What do we do when we take something seriously? We make a plan. Agile development is nothing more than saying, 'stop overplanning!'. You need a plan. The default plan is the James Joyce stream of consciousness, whatever comes to the top of your head. That's not a good plan.

Zoom In

Work your way down from the big picture to the little picture. You're working on the shopping cart page. Why are you working on that? We're making an e-commerce site. Why? We want to make money. The absolute best top-down explanation doesn't come from technology, it comes from Abraham Lincoln. The Gettysburg Address starts with the founding of the American Republic, saying "Four score and 7 years ago... now we are engaged in the great civil war... we are met here on a great battlefield...". In 3 sentences, he takes it from the top down to right here and now.

Zoom Out

Bottom-up vs. top-down. When will you use one over the other? It depends on who's asking. An investor wants the top down, a coworker wants the bottom up.


Consider the assembly line. Describe the route taken through the system. Example: Scholastic Rock and the Bill on Capitol Hill.


How did we get here? ... once upon a time, there was a guy named DHH. He thought creating web applications was too hard... etc.

4. Be Agile

Do it, Measure it, Fix it, Repeat.

We tend to make explanations and use the same explanation over and over without making it better. How do we make it better? We ask questions. "How am I doing?". A few key things we are looking for: Silence, Blank Looks, and the Same Questions.

It's all too easy to blame it on the person you're trying to explain it to. Your job is to explain it. It's your responsibility to make the explanation succeed. It's not them, it's you.

There is one major failure mode in explanations. The first thing you should look for is the gap.

Mind the Gap

You explain A, suddenly stop and move on to B, and they haven't understood A.

When you're learning, you have to think through everything. What was the Spanish word for Red? ..... it was ..... "rojo"! That's it! After a few years, it becomes second nature. Remember your first Ruby programs? After a while you've internalized that knowledge. Internalizing is excellent for usage, but terrible for explanations.

Experts know it so well, they forget there is anything to know.

Explaining Rails: What's the first thing? OOP? MVC? RVM? Installation? Bundler? Ruby? Models? Where is the gap? 

The student might suddenly realize: "Ohhhh, I get it! Ruby is the language, Rails is the Framework!" .... and you'll think: "Well, yea!" They didn't know that, and you didn't know that you knew that.

Hold on to the gaps.

3. Explaining is a Timed Event

Baseball is by innings, football is by time. Which kind of sport is explaining? We tend to think it's like baseball: I'll explain A in the first inning, B in the second inning, etc...

Explaining is a timed event. When the time is up, you're done. The timer is in the head of the person you're explaining it to.

Put the important stuff first.

The terminology is not important stuff. Don't lead with that.

You've lost the person when you start with the terminology.

Start with the concept and then define it. They may lose the term, but they'll likely retain the concept.

You can move the timer back, or you can make it move really fast. Want to speed up your timer? Say "this is really hard" up front. 

To move the timer back, tell them it's hard after they've gotten it. "Now that you get this, guess what? This is the hardest part." The learner will feel good about themselves.

2. Repeat Yourself Enough

There is a certain level of repetition that every good explanation has. 

Repeat yourself for 

  • Emphasis
  • Context

Don't sound like the IRS. "For more information, refer to Section 9.7." vs. saying, "Remember that in Section 9.7, we learned..."

1. Mix in Some Humor

Any explanation with a little bit of humor in it is going to be a better explanation. If you're great at telling jokes, or sort of funny, don't let the jokes get in the way. Subtle is better. And don't explain the jokes.

What if you're not funny, and you know it?

Congratulations, you're head and shoulders above the people who aren't funny and don't know it.

But you don't have to be funny!

Mix in some Humanity

Show up and bring a little bit of yourself.

Justin Gehtland brought Hannibal Lecter, Sandi Metz brought the recumbent bike, Roy Tomeij brought Bob Ross, and so on...

comments powered by Disqus