Hey lovely readers,
Have you ever explained something you know really well, looked up, and seen a room full of blank faces? I have. More than once. And most of the time, the problem wasn't what I said. It was the order I said it in.
As a speaker, teacher and mentor, I explain things all day long. To students, to junior developers, to clients, and even to kids. Over the years I noticed that there are two main ways to build an explanation: top-down and bottom-up. Both work. Both can also go very wrong.
And you don't have to be a speaker for this to matter. As developers, we explain things all day: in pull request descriptions, code reviews, READMEs, onboarding sessions, standups, and every time a product owner asks why that "small change" takes two sprints.
In this blog post I'll show you the difference, when to use which one, why your audience matters so much, and the little trick I use in almost every talk I give.
What is a top-down explanation?
A top-down explanation starts with the big picture. You first tell people what something is and why it matters. Only after that do you zoom in on the details.
Think of a LEGO set. The front of the box shows you the finished spaceship. Before you touch a single brick, you already know what you're building. Every step in the manual makes sense, because you know where it's going.
Now a developer example. If I explain async/await top-down, I start like this:
async/await lets your app keep doing other work while it waits for something slow, like a database call or an API request.
That's it. One sentence, no code yet. After that I show what a Task is, what the await keyword does and what happens with the thread. The listener already has a place in their head to put all those details. People remember details much better when they know what the details belong to.
The same works for walking a new colleague through a codebase. Top-down, you start with the architecture: "This is an ASP.NET Core Web API with three layers. Requests come in through the controllers, the business logic lives in the services, and EF Core talks to the database." Only then do you open the solution and show where each part lives.
What is a bottom-up explanation?
A bottom-up explanation does the opposite. You start with the small building blocks and put them together, piece by piece, until the big picture appears on its own.
Back to LEGO. Now imagine someone hands you a bag of bricks without the box. You click two bricks together, then a few more, and slowly you start to think: wait, is this a wing? Oh, it's a spaceship! That moment can feel amazing. It can also feel very confusing if it takes too long.
The async/await example bottom-up would start more like this:
Your code runs on a thread. A thread can only do one thing at a time. So what happens when that thread has to wait three seconds for the database?
Then you introduce Task, then await, and only at the end you say: and that is why async/await exists.
And the codebase example? Bottom-up, you pick one endpoint, set a breakpoint and follow a single request: from the controller, into the service, through the repository, all the way down to the DbContext. Do that for two or three endpoints and the architecture becomes clear on its own.
Bottom-up explanations are great for building real understanding, because people see why every piece is needed. They just ask a bit more patience from your audience.
When top-down works best
In my experience, top-down is the safest choice in most situations. I use it when:
- People come from very different backgrounds. Some know a lot about your topic, some know nothing. A short big picture first gives everyone the same starting point.
- People need to make a decision. Clients and managers usually don't need to know how every piece works. They need to know what it is, what it costs and what it changes for them. So start there.
- Time is short. In a 20 minute talk or a lightning talk, you don't have time to build things up slowly. If you run out of time halfway through a bottom-up story, people go home with a bag of bricks and no spaceship.
- The topic is new for everyone. Without a map, beginners get lost really fast.
- You're writing an abstract, an intro or a README. The first sentences should tell people what they're going to get.
When bottom-up works best
Bottom-up shines when people are doing, not just listening. I go for it when:
- It's a workshop or a live-coding session. People type along and build the thing themselves, step by step. The "aha" moment comes from their own hands, and that sticks.
- The audience already has the wrong picture. If people think they understand something but they don't, starting with the big picture only confirms their wrong idea. Going back to the basics lets you rebuild it properly.
- The audience is advanced. Experienced developers often want to see how something works under the hood. They already have the big picture, so give them the bricks.
- You're debugging together. When you help someone fix a bug, you start with what you can see (the error, the log line) and work your way up to the cause.
- You want a surprise. A good reveal at the end of a talk is a bottom-up trick. Just make sure the road to that reveal is fun.
Your audience is more diverse than you think
When you speak at a tech event, you never really know who is in the room. There are juniors and seniors, backend and frontend developers, people who write code all day and people who manage the people who write code. There are people listening in their second or third language. And there are people whose brains simply work differently from yours.
Neurodivergent people, for example autistic people or people with ADHD or dyslexia, are in pretty much every audience, even if you can't see it. So when you explain something the way your brain likes it, there's a good chance it doesn't work for part of the room.
This is where bottom-up explanations really shine. Many autistic people process information from the details up: they collect the pieces first and then build the bigger picture themselves. Temple Grandin, a professor at Colorado State University and one of the best-known autistic voices, describes her own thinking exactly like that in her personal account: find lots of little details first, then put them together into concepts. If you start with a vague, abstract big picture, that can feel like getting a conclusion without the evidence. Concrete examples, clear steps and explicit connections between those steps help a lot.
At the same time, neurodiversity is broad. Not every neurodivergent person thinks bottom-up, and some people actually need a clear map first to stay focused. So what do you do with a room full of different brains?
My favorite: zoom out, zoom in, zoom out
So which one should you pick? Honestly, I almost never pick just one. Most of my talks follow the same pattern:
- Zoom out. Start with the big picture in a few sentences. What is this, why should you care, and what will you know at the end?
- Zoom in. Now build it up bottom-up. Small pieces, one at a time, with examples and demos.
- Zoom out again. Bring everything back together. Show the big picture one more time, but now people understand every piece of it.
It's the LEGO box again. You look at the picture on the box, you build the spaceship brick by brick, and at the end you hold it next to the box and think: I made that.
If you've read Public Speaking at Tech Events 101: From Acceptance to the Stage, you might recognize this. There I made a rough sketch of a talk: an intro, some context, the core of the talk, a demo and a conclusion. That's exactly this pattern. The intro and context zoom out, the core and the demo zoom in, and the conclusion zooms out again.
It also works on a much smaller scale. One slide, one paragraph in a blog post, one answer to a question from a student: give the headline first, then the details, then repeat the headline.
Top-down and bottom-up in your daily work
You don't need a stage to use any of this. This is where I see it come back in a normal week as a developer:
| Situation | What usually works | Why |
|---|---|---|
| Pull request description | Top-down | Reviewers want to know what changed and why before they open 40 files. |
| README | Top-down | What does it do and how do I run it? The details can come later. |
| Tutorial or getting-started guide | Bottom-up | People build something step by step and the concept clicks along the way. |
| Bug report or GitHub issue | Both | A top-down title ("Login fails for users with 2FA enabled"), then bottom-up steps to reproduce. |
| Onboarding a new team member | Zoom out, zoom in, zoom out | Architecture overview, follow one request through the code, then back to the overview. |
| Explaining to a product owner or client | Top-down | They need the impact, not the implementation. |
| Mentoring a junior developer | Bottom-up | Let them write the code and discover why each piece is needed. |
| Live-coding demo | Bottom-up, with a top-down intro | Show the end result first, then build it line by line. |
Your code is an explanation too
The same idea even shows up in the code itself. I like to think of a class as a news article: the headline and the most important parts sit at the top, and the details get smaller as you scroll down. That's top-down. Someone opening your class sees what it does before they see how.
public class OrderService { public async Task PlaceOrderAsync(Order order) { ValidateOrder(order); await ReserveStockAsync(order); await SaveOrderAsync(order); await SendConfirmationAsync(order); } private void ValidateOrder(Order order) { /* ... */ } private async Task ReserveStockAsync(Order order) { /* ... */ } private async Task SaveOrderAsync(Order order) { /* ... */ } private async Task SendConfirmationAsync(Order order) { /* ... */ } } Reading PlaceOrderAsync gives you the whole story in four lines. Want to know how the stock gets reserved? Scroll down. Your colleagues (and future you) will thank you for it.
Common mistakes
Both approaches can go wrong. These are the mistakes I see the most (and yes, I've made all of them myself).
Lost in the bricks
The classic bottom-up mistake: you spend twenty minutes on details and nobody knows why. People stop listening. Not because it's hard, but because they don't know what they're listening for. If you go bottom-up, at least tell people where you're going. Even a simple "in fifteen minutes this will all make sense, I promise" helps a lot.
All box, no bricks
The opposite mistake happens with top-down. You keep talking about the big picture and never get concrete. Think of an architecture talk with fifty slides of boxes and arrows, and not a single line of code. Everyone nods, but after your talk nobody can actually do anything with it. A big picture always needs at least one real example.
Jumping between levels
Big picture, tiny detail, big picture again, a different tiny detail. This happens a lot when we know a topic really well, because everything feels connected to everything. For the listener it feels like a camera that keeps zooming in and out. Pick a direction and stay with it for a while. Zooming in and out on purpose, like in the pattern above, is great. Zooming at random is what loses people.
Forgetting what it was like not to know
When you know something well, it's hard to remember what it was like to not know it. A step that feels obvious to you might be the exact step someone else is missing. That's why testing your explanation on someone who doesn't know the topic is so valuable. Students and kids are very honest about this :)
Questions to ask yourself before you explain
Before I start working on a new talk, blog post, lesson or even a bigger PR description, I ask myself these questions:
- Who is listening? Beginners, experts or a mix?
- What do they already know, and what do they think they know?
- What do they need to do with it afterwards? Make a decision, write code, or just understand it?
- How much time do I have?
- Will they be listening or doing?
The answers usually point you in the right direction:
| Situation | Try |
|---|---|
| Your audience is new to the topic | Top-down |
| Your audience needs to make a decision | Top-down |
| You only have a few minutes | Top-down |
| People are coding along with you | Bottom-up |
| Your audience already has the big picture | Bottom-up |
| People have a wrong idea about the topic | Bottom-up |
| Your audience is very mixed, or you're not sure | Zoom out, zoom in, zoom out |
That's a wrap!
Top-down gives people the map first. Bottom-up lets them draw the map themselves. Neither one is better. It depends on who is listening and what they need. And when you combine them, you get the best of both.
So the next time you explain something, whether it's on a stage, in a pull request or at the coffee machine, take five seconds to think about the order. It makes a bigger difference than you might expect.
Do you prefer top-down or bottom-up explanations yourself? Let me know in the comments, I'm really curious! And feel free to reach out on my socials if you have any questions.
See ya!