Has THIS ever happened to YOU?

You're in a meeting with a bunch of other developers. The presenter, who is one of the smartest people you will ever meet, starts off by saying "I know you mostly aren't familiar with the FroznakDecombobulationService, so I'm going to give everyone a high-level overview. As you will see from the boxes and arrows on this slide, ..."

Fifty minutes later, your coffee cup is empty, your bladder is full, your notepad is full of explanation on all the different frameworks and architecture patterns that the FroznakDecombobulationService runs on, and all the different types of error state it might encounter. But somehow, you've never managed to figure out what a Froznak is, or why it ever needs to be Decombobulated by a dedicated Service -- and you're not really clear on the core workflow of the service either.

Developers tend to be very good at writing code -- or at least, we hope we are. Developers do not always tend to be good at explaining their code to outsiders. In my experience, it's especially easy for developers who may have spent months or even years working in the same specific problem space, learning all about the ins and outs of their particular piece of software and its role in the broader environment, to forget that no one else understands their particular niche better than themselves. So in my experience, most presentations given by a developer on a particular piece of software that they work on tend to focus exclusively on the fine details, at the cost of the broader picture. This is more than missing the forest for the trees -- it's missing the trees for the bark and the leaves, and never even considering that your audience has no idea what the forest looks like.

The good news is that if you're considering giving a presentation about some software that you're working on, it's easy to do a lot better than this. All you have to do is keep in mind that your audience, though they may be very smart people who know a lot about software, probably don't know much about your specific software -- if they did, they wouldn't need a presentation! You can model your audience as needing answers to three basic questions about your software, and then all you have to do is answer these three simple questions, in order:

• WHAT problem does this solve for the customer?
• HOW does it solve the problem?
• WHY does it solve the problem that particular way?

WHAT?

Every software system exists to solve some particular problem. If it didn't make someone's life easier (or at least try to), no one would build it. For some systems this is obvious -- for example, a customer facing UI might allow customers to update their account details in your database. But it's often less clear -- a back-end logging service for this UI may not even be visible to customers, but hopefully it helps solve errors and outages faster, thus keeping your customers happy. A caching service might keep latency down, thus giving customers faster response times, while it also keeps server costs down, which gives customers lower prices. Hopefully you understand what value your software system provides to customers, but if not, that's probably something you should figure out before you start trying to explain it to anybody else.

HOW?

This is the part that everyone knows they have to explain; but it makes a lot more sense when everyone listening already understands what problem your system is trying to solve. A useful way to start is by estimating how much you think your audience might understand already, and then cut that rough estimate in half--that's probably about how much they actually understand (and that's why you're the one presenting, to them!). With this safe assumption in mind, it's usually best to try and organize your explanation top down, by starting at the highest level of the overall design, and then drilling down steadily into more and more details. Visual aids like flowcharts are always a great call here, as is literally just showing people the code you're talking about.

WHY?

This is the part where you can really nerd out -- and hopefully if you've engaged your audience enough, they'll join in. Now that everyone knows what your system is doing, and how it's doing that, it's a lot easier to explain why it works the way it does -- the design decisions and constraints that have gone into it, the things that are really cool or that you're rightfully proud of, or the pile of horrible hacks that nobody likes that got forced into the system by its inherent constraints. This makes a good capstone for any presentation because the What and the How segments have flowed naturally into the Why, by providing context and raising implicit questions about the decision-making (or lack thereof!) which led to the system's current state.

None of this is intended as a strict set of rules; different situations call for different approaches. But I do find out that by keeping these questions in mind any time I have to explain a technical system, and making a point to answer each of them more or less in order, I can plan presentations more easily, and people tend to be more engaged during them, which seems to result in better transference of information and understanding.