Scheme I: “Explanation Loop”

I-I, say that you remember! It’s the month of I, so we’re going to get personal again. Kind of. A little.

One of the most important skills of a developer is the ability to exchange information, and more specifically, to give suggestions and explanations. To explain explanations: I’d say the goal of an explanation is to give someone information that 1) they don’t know and 2) is useful.

In my time working, and also being a person, I’ve done that badly many times, and seen it done badly as well. I’m not some sort of communication expert, but I’ve found a loose structure that helps me avoid some common pitfalls. I’ll call it the explanation loop, which sounds much more official than it actually is.

# Definition

When you explain or suggest something, you make sure you’re doing it in an information-seeking and empathy-providing loop.

# The story

I’m going to tell two stories that, in my opinion, show opposite ends of explanations gone wrong.

# Underestimating knowledge is frustrating and wastes time

Once, a more senior dev was about to give me a proposed improvement to my code. Before proposing their suggestion, they asked if I knew a specific term. I said no, and made an educated guess, which was wrong. The senior dev then went into a detailed explanation - seconds into it, I realized I did know the concept, as it was basic middle school math; but I went to school in the French system and didn’t know the term. I couldn’t successfully interrupt them, this explanation took a while, and it wasn’t really useful, as it was only tangentially related to the suggestion.

# Overestimating knowledge is frustrating and wastes time

A junior teammate asked me for help debugging their code. I started out with my idea of a solution – but every few words, I could tell they didn’t quite get it, so I’d interrupt myself, ask if I should explain, then continue my explanation. I’d go like “you could go with a functional solution – actually, sorry, you familiar with functional programming? No? well, here’s what that means… anyway, I was saying, you could write this in a functional way, and destructure the argument – are you familiar with destructuring? Here’s an example of destructuring on line 17…” In short, I’d mention terms that I assumed were familiar, and since they weren’t, I’d go into a bunch of disparate explanations.

# Why we did it wrong

I think in those cases, the explainer ran into the main problems when giving explanations:

• Misjudging the other person’s level of knowledge
• Talking too much

Obviously, these two are related.

If you’re talking too much, you’re not trying to understand whether your explanation is hitting.

If you’ve misjudged how much the other person knows, you’ll probably explain something unnecessarily, or explain things at such high level that you’ll have to backtrack and break them down, which leads you to talking too dang much.

# How I try to do it now

Over time, I’ve come to develop a loose framework for explanations and suggestions. It goes, basically:

1) Empathize 2) Ask for information 3) Provide information (in a loop)

As an example, if my coworker comes to me for help debugging code, I try to have things go basically like this:

C: “I need help debugging this code.”

Me: “Sure thing, what’s the problem?"

C: “So, I am trying to process data from an API, and every now and then, this function is giving me a different output than expected.”

Me: “Huh, weird. Can you show me an example?”

C: “Yeah, here, if I run it 5 times in a row with the same input, occasionally, the result is different.”

Me: “Hmm. Maybe something has a side effect in this function, like it’s modifying one of the variables you’re depending on…”

I stop there. It’s important not to be afraid of a little bit of silence. My coworker’s response helps me understand their level of information in this particular situation.

Maybe my coworker is very comfortable with what I just said, in which case we’d restart the loop:

C: “Yeah, I’ve considered that, and I’ve tried [ie making it functional to avoid side effects, but ran into this issue…]”

Me: “Right, makes sense. With the way it’s set up now, it’d be be a big refactor. That’s frustrating. Did you find out anything, though, like is there anything that’s definitely not the cause?”

Or, alternatively, they might want me to elaborate.

C: “How do you mean?”

Me: “Oh, yeah, sometimes you might be affecting a variable that’s defined outside your function - let me find some docs on functional programming, they probably explain that concept…”

Side note, sometimes, the conclusion of all of this is “Well, I’m really not able to help you, let’s figure out next steps.” In my experience, even then, we get there a lot faster when there’s a constant feedback loop.

# My plan

Underestimating someone’s knowledge is a problem, because you waste time explaining things that they already know. It can be insulting for them, and embarassing for the both of you.

On the other hand, overestimating it puts the person in the awkward position of needing a lot of clarification. You can also end up explaining concepts that are too high-level to be useful, just because you’ve mentioned the technical term and they didn’t know it.

When I use the empathize-ask-provide loop, I am trying to give the other person as much agency as possible in getting the right kind of help. Specifically, if there’s gaps in our communication, the loop brings them out fairly quickly / often, and it stops me from rambling too much.

# Caveat

I have one big caveat to this: putting on an act defeats the purpose. This scheme can feel a bit unnatural, but the whole point is to be efficient and respectful, and dishonesty is rarely either of those things.

For example, I’m not a fan of pretending I don’t know the problem or solution. I’ve had people think they know the answer to my problem, and try to guide me to it. I find that really condescending.

If I think I know the answer, I’ll say it upfront: “I see this variable is modified on line 17.” Or, if I am in an explicit mentor-mentee situation, where I’m teaching someone, I might say it in a veiled way, like: “I see a place in your function where a variable is being modified, that’s probably what’s making the return inconsistent, did you see that?” My mentee might ask me for details, or want to look on their own - either way, I want to keep them in control.

# PS

There’s another major caveat, which is that these are live conversations. When you’re dealing in async communication, the scheme is totally different. I might talk about how I deal with that in a further post… or not.

Also, this is my second post about social skills, and again, it feels vulnerable to write about guidelines for that, but I’m convinced social skills take some level of practice and intention for everyone. Anyway, see you next month, K!