I was recently fumbling my way through a programming problem. I couldn’t figure out the root issue, so I cobbled together a shaky solution and posted my ¯_(ツ)_/¯.

Then Sam Stephenson stepped in to help. I admire and respect Sam a lot — he’s patient, thoughtful, and wicked smart. He wrote such a well-crafted response to my post that I consider it one of the best teaching moments I’ve experienced. Here’s his response in its entirety (discussion about why it’s so great follows):

Why do I think this such a great teaching post? Let’s break down it down…

It’s clear and thoughtfully constructed

Sam’s post was so clear that as I read it, I felt like he was walking me through it in person. This is no accident — he’s an excellent writer. How did he do it?

Take a look at the structure of the post. He identifies the root cause, outlines a broad conceptual solution, demonstrates a concrete solution, and lastly summarizes. That’s an excellent pattern to follow.

The “design” of the writing is important too. He uses short paragraphs to make the post readable. The words he chooses are clear and simple, and avoid unnecessary complexity. And he makes effective use of contextual elements (quoted text, linked text, and images) to help illustrate his point.

It’s concise

In a mere 213 words Sam articulates the issue and a potential solution. That isn’t easy — a post like this could easily be 2–3 times as long. There’s no fat in his post. It’s thorough, direct, and doesn’t wander around non-essential details. He makes his point and gets out.

This is critically important. It’s very difficult to parse out what’s important if it’s buried in fluff. Keeping the post focused is a big part of why it’s effective.

It’s directional, not a direct solution

A great way to teach is to point someone in the right direction, but not give them the exact answer or code snippet. Let them figure out the details and learn from whatever issues come up as a result. In other words, don’t be Stack Overflow.

In this case, Sam’s given me plenty to work with. But it’s not a direct solution I could lift into our code, and that’s a good thing.

It goes the extra mile

Sam is Ruby/Rails expert, not an Android developer.

Yet he put the extra time and effort into setting up an Android development environment and working through a proof of concept. Nobody asked him to do it — he just did it! He could have very easily responded with a one line post saying “Did you try this…”, and we probably would have gone back and forth a dozen times on it. But he didn’t. He slowed way down, worked through the solution (in an unfamiliar development environment), and posted a thorough response a day later.

In the long run, Sam’s extra effort saved us time (no back and forth discussion), made the app better for customers (I fixed the app in a couple hours) and taught us all something new.

This was an exceptional bit of teaching by Sam. It’s an example I hope we can all learn from and aim for. Every day we have opportunities to teach others. Often we ignore them or give them only a few minutes of our day. But I hope this example shows how impactful teaching can be when we put genuine effort into it.

I’ll never forget what Sam taught me here — no, not just the technical bits. Really what he ended up teaching me was how to be a better teacher.