Explain technical concepts fast with metaphors

Metaphors are one of the first tools we reach for when trying to explain complex technical concepts, and we often use them without even realising. Look at that last sentence. Tool is a metaphor, and so is reach! They're pervasive — but that's because they're so useful.

But some metaphors are more powerful than others. A bad metaphor can confuse a learner, while a great metaphor kick-starts the process and makes it clear where the remaining gaps in their knowledge are.

So what makes one metaphor bad, and another amazing?

A terrible metaphor just maps objects

Let's start by defining what a metaphor is. That way, I can show you the worst-but-still-technically-valid metaphor I can think of. Then we can discuss why it's so useless.

Metaphor

• a figure of speech in which a word or phrase is applied to an object or action to which it is not literally applicable
• a thing regarded as representative or symbolic of something else

So, a metaphor is any time we use figuratively use one thing to represent another. I can do that! Here goes:

Our API is a banana

There we go. Perfectly valid metaphor right there. Package it up and ship it. Job done. Article finished. Everyone understands how great metaphors are right now. Right?

Something is missing

That banana metaphor is technically valid, but it's pointless and doesn't teach you anything. That's because it's missing the most important part of a metaphor — something that they dictionary definition doesn't cover at all.

Think about your initial reaction to 'Our API is a banana'. I'm guessing it was something like 'Okay, in what way?'

That's because a metaphor's power is not about the concepts themselves, but in the interactions between those concepts.

In this case, our metaphor maps a concept (the API is a banana) and then stops. It never mentions interactions, nor can you really guess from the context what those interactions might be. A better metaphor would map multiple concepts and the interactions between those concepts.

An okay metaphor maps interactions too

Let's take that idea of mapping multiple concepts and their interactions at face value and come up with a metaphor that's better, but still not great:

Our API is a restaurant menu listing all the data you can order from us

This is definitely an improvement. We map two concepts in real life to two objects in the metaphor. We never explicitly mention food, but the implication is good enough. Most importantly, the interaction between the two concepts is also covered in the metaphor.

So now if you ask 'In what way?', the answer is that both the API and the menu list the available options.

However, 'Our API is a restaurant menu' still isn't a great metaphor. It has a problem, and part of you already knows what that problem is. The part of you that's saying 'Okay but what about prices / waiters / tablecloths / the wait time / the little basket of bread they give you sometimes?'

The expanded metaphor universe

The true power of metaphors come when they let you infer things. They let you use your existing knowledge about one concept to learn new things about an unfamiliar concept.

When you hear that our API is a menu, you immediately start to think of all the other interactions you have with a menu. Most importantly, you assume that all the interactions you have with a menu in real life must also map back onto the API. If our API is a menu, and a menu lists prices, then our API must list prices too.

In our menu metaphor, very few of the other interactions with a menu can be mapped back onto an API. A menu lists the food, but it also lists drinks, and daily specials too. So if our API is a menu, and it offers a data where a menu offers food, then you must also be able to request things other than data, since a menu doesn't just list food.

...and some data must only be available on a Thursday. Oh, and when your food comes at a restaurant, you eat it and then it's gone. So you have to request the data each time you want to use it, right? You can't have your data and eat it.

Of course, this is a contrived example. In practice, nobody is going to hear 'Our API is a menu for data' and ask about the daily specials. It's almost impossible to create a metaphor that works for all of those inferred interactions.

But we can still try...

A great metaphor helps you make assumptions

Our menu metaphor was good, because it included multiple concepts and the interactions between those concepts. However, it didn't help us transfer our existing knowledge about adjacent concepts.

A great metaphor would let you use your existing knowledge about the metaphorical objects to infer things about the unknown concepts:

Our API is the door to your data

That might not seem too different to the menu example, but it really shines when you start to infer other interactions between a door and a house:

When you hear 'Our API is the door to your data', you might start thinking about how a door can be open to let anyone through, or it can be locked, only letting people with a key through. You might infer that an API would work the same way, and you'd be right.

You might think about the fact that your house has two doors, not just one. Maybe you can access your data with multiple different APIs. And you'd be right.

You might think about how a house stops your belongings from getting wet when it rains, and try to think of what that would mean for an API and your data. Maybe an API helps you still get access to your data, even when the environment outside is inhospitable? Kinda, in the sense that APIs will limit the impact of bad actors via rate limiting. But that one's a bit of a stretch.

As for the fact that doors can be made of wood or glass? You could probably come up with something, but I left that as a reminder that it's almost impossible to make a perfect metaphor. There will always be some interactions that don't map nicely.

The power of a great metaphor

Great metaphors make it quicker and easier to learn new topics by allowing you to transfer your existing knowledge onto a new concept. In the last example, all we said was 'Our API is the door to your data', and immediately you're thinking:

• APIs are used to access data
• You might be able to have multiple different APIs for one bit of data
• Some APIs could be open to everyone, while others need a key. If I lose my key, I could talk to the people inside and they'll let me in.
• The API helps protect my data
• Some APIs automatically close themselves because they're fire-rated and if I use a doorstop I'll get in trouble

Now clearly, not all of that is exactly correct. However, it's a great starting point for a conversation. It lets the learner, who previously knew nothing about APIs, lead a conversation with an expert and ask questions to check their understanding.

Thanks to our metaphor, our learner can immediately make some assumptions and ask 'Can you have multiple APIs for the same data, like how my house has a back door?' — a much more effective way to learn.

So the next time you reach for a metaphor when explaining a difficult-to-understand concept, think about what you could infer from it. Is there anything that the listener might infer, that would confuse them? Clarify it for them.

I'd like to acknowledge Caitlin Walker and her book 'From Contempt to Curiosity' for getting me thinking about the theory behind metaphors and what makes them so powerful. It's a great book, and I highly recommend it.

This post isn't the usual kind of thing we publish on the TalkJS blog, but I'm passionate about metaphors and wanted to share. Let us know if you enjoyed it, and you can always read more of my rambling over at my personal blog!