Crafting Compelling Tech Narratives: A Developer's Guide to Better Teaching

There's a constant flood of new information for developers to absorb. But how do we effectively share what we've learned? Whether it's through presentations, articles, tutorials, or mentoring, the key isn't just to list facts, but to weave them into a compelling narrative that helps others truly understand.

The Flaw in a Timeline-Based Presentation

Recently, I gave a keynote presentation on the evolution of Gemini over its first year. The structure was a simple timeline, detailing every single feature that had launched—dozens of them. Afterward, while the feedback was positive, one comment stood out: "It was a good presentation at the end, but by the middle, you were just telling us what was going on."

That comment hit the nail on the head. The presentation felt like a list: "And then we got this feature, and then we got this feature..." While I occasionally explained a feature's benefit or a new model's cost-effectiveness, I had lost the overarching story.

The core problem was the lack of a clear narrative. I failed to frame the journey from start to finish. I should have established a baseline: "Here's what you could do at the beginning and for how much," and then contrasted it with, "and here's what we can do now, and how much cheaper it is." The story should have been about the value gained along the way. The final message—imagining the next year and empowering the audience to build—landed well, but it lacked the foundation of the preceding 20 minutes. I never connected the dots from the introduction of a feature like function calls to how they are now better, faster, and cheaper.

Understanding why you're doing something is just as important as knowing how to do it. This is a crucial part of helping people learn.

The Power of Storytelling

A number of years ago, the book Made to Stick highlighted the importance of telling a story. In any medium, whether a presentation or a long-form article, a narrative makes information easier to digest than a blast of facts. This is how we naturally learn; we construct an internal story of how we came to understand a topic.

However, every developer approaches a subject with a unique background—different programming languages, different experiences. What seems clear to us might not be to someone else. We often need to step back, define our terms, and explain our approach. This context is part of the narrative. The constant struggle is presenting all this information in a compact, digestible form, and the structure of a story provides that natural compactness.

Learning by Creating and Sharing

When learning something new, like the intricacies of the Blue Sky App Protocol and Jetstream, a great strategy is to document the journey. As you read different sources and watch tutorials, you begin to form a mental model.

Note: A great way to solidify this model is by creating your own "quick guide."

This guide doesn't need to be exhaustive but should include key elements: - A glossary of terms: Define the core concepts. - Diagrams: Visuals are incredibly powerful. If none exist, create them. A diagram helps set boundaries around a concept. As you learn more, you can update the diagram, which reinforces the learning process.

Once you have this guide, you can share it. Creating a short article or screencast that walks through the guide is immensely helpful. You can explain why things are structured the way they are.

Pro-Tip: The 2-Minute Hook When creating instructional content, try to show something in action within the first two minutes. Let the reader see a result—like connecting to a WebSocket and seeing data stream in. This creates an immediate payoff and hooks them. They won't want to read for 15 minutes just to get to the point.

You Don't Need to Be the World's Foremost Expert

There's a common fear that you must know everything about a topic before you can write or speak about it. This isn't true. Sometimes, being just two or three steps ahead of your audience is all you need. You can frame it as, "Last week I knew nothing about this, and here's what I've learned." This can provide the critical boost someone needs to get started.

Committing to a presentation or an article is one of the best ways to learn a subject because it forces you to understand it well enough to explain it. Don't be afraid of being wrong. If someone corrects you, you've just learned something new and have the basis for a follow-up article.

From Sample Code to True Understanding

Many developers look at sample code and think, "This is a lot to digest. What are the two lines I need to get started?" This is why simply following sample code isn't always the best way to learn. It's easy to see that it works without understanding why.

A better approach is to take on a challenge: "Here's something you can do with this tool; go figure it out." This forces a deeper understanding of what each part of the code does.

This is where modern AI tools are becoming invaluable. They can explain complex code chunks. For example, when encountering an unfamiliar syntax in a new version of Java used in the Spring AI tools, you can simply ask an AI:

// Hypothetical unfamiliar Java syntax
var result = processRequest(request ->
    new Response(request.id(), "Processed")
);

And the AI can explain, "This is a lambda expression passed as an argument, a feature enhanced in recent Java versions." Suddenly, you've learned a new concept. The goal isn't just to get code that works, but to ask, "Why does this code work and my original attempt didn't?"

The Art of Mentoring

Mentoring is a conversation. It's about working together to reach a common understanding. Unlike writing an article, you get immediate feedback, which is both an advantage and a disadvantage. If a mentee says, "I don't get it," and you don't know how else to explain it, frustration can build on both sides.

It's crucial to create a safe space. Acknowledge that you don't know everything either. Phrases like, "Let's just noodle on this together," can lower anxiety and foster collaboration. The goal is to figure out where the other person is coming from. Are they brand new? Do they have partial knowledge? Their starting point determines your approach.

Ultimately, whether you're on a stage, writing an article, or mentoring one-on-one, the goal is the same: to work with your audience to build a shared level of understanding. That collaborative spirit is the foundation of all effective technical communication.