Speaking Technically: Detail Oriented
You’ve built a new piece of software, hooked up the network, or upgraded the OS on a thousand machines. Now, you want to tell your bosses, your co-workers, and end-users what this means for them, and that means you have to explain your technical system.
Technical systems can be broken down into two types: the trivial and the overwhelmingly complex. There isn’t much middle ground. A program complicated enough to do anything interesting is complicated enough that you can’t understand it in a single glance.
Smacking your audience upside the head with too many details, too quickly, descends into the technobabble effect. The brain can’t absorb that much information all at once. It falls back on its defense mechanism against overload: boredom.
The problem is that you need to communicate all of the details, accurately, without boring anyone. You need to reveal them in a logical, ordered fashion that connects with the big picture. This is a tall order.
The Controlling Idea
What is your story about? Like most absurdly simple questions, it’s much harder to answer than it might look. A science-fiction story may be set in some far off future, but it’s never about the future. Science-fiction is always about the era in which it’s created.
Your technical stories need to be the same way. They’re not about the system, tool or technology you’re specifically talking about. Your technical story needs to be about what matters to your audience.
You need to put on your user hat, and think about why the user cares about this tool or change. Why does your boss care? Knowing your audience is hard. You have to listen, carefully, to the people around you to understand what they might care about.
The controlling idea of a story is what the story’s about. Your controlling idea needs to reflect the interests of your audience. Your boss cares about how your tools allow you to do more, with less, and make them look good. Your end users care about how your tools help them get work done. And your peers want to know how your tools keep them from getting 3AM phone calls to fix something that’s broken.
Once you know what the controlling idea is, you can start identifying the key details. The key details are the ones that play the largest role in giving your audience what they want. That varies by audience. You need to be able to look at your system from different angles, and understand what’s most important from that angle, be it the “boss angle”, the “end user angle”, or the “everything’s broken and it’s time for a little CYA angle”.
Agency
You’ve identified a few key details, but each of these details is itself a complicated thing that requires understanding lots more details. How do you identify and prioritize which details matter the most to supporting your controlling idea?
Identify the details that have agency. Here, it helps to think of our modules and components as if they were people. You want to find the modules that are the leaders, the ones that give the orders, the ones that provide direction.
This is a relative thing. For example, in the common “model-view-controller” design pattern, we have three key components:
- Model: the data being manipulated
- View: how we show that data to the user
- Controller: the logic that binds models and views together
This design pattern is popular, in part, because it has only one truly active component: the controller. The controller tells the other parts of the application what to do. They’re all important- removing any one means the application stops working- but the controller is the one component that has agency. It does things and tells the model and the view what to do. It’s the “main character” in our story, while the view and model are “supporting characters”.
This line between active components and passive components can be subjective. Like our key details, it’s going to change based on the audience we’re talking to. Divide your list of key ideas into two lists: “active/main characters” and “passive/supporting characters”. With those in hand, you can now identify…
The Through Line
You have a technical system. It delivers some value. You have a bunch of details about how it delivers value, some “active”, some “passive”. Now you need to connect those dots. The way you build that connection is the through line.
The through line is often described as the “glue” of a story, but I prefer to think of it as the flow of the story. It’s the clear path that guides the audience through the story. It takes all of the raw facts of the story and gives them meaning in relation to the controlling idea.
In Star Trek: The Wrath of Khan, Kirk’s refusal to surrender pulls us through the story. The events and the facts of the story- Saavik’s Kobyashi Maru test, Kirk being marooned, the final battle in the Mutara Nebula, and Spock’s death- are all held together by the through line of Kirk’s statement: “I don’t believe in a no-win situation.” We see Kirk struggle through all of his challenges until he finally confronts the real “no-win situation”: Spock’s death.
There’s an art to this, and the approach you take will be different for every technical story you tell. There’s no right answer and no specific formula for doing it.
I tend to think of it like data flow diagrams, or UML Sequence Diagrams, because those are tools I use as a programmer. As you practice, you’ll find your own techniques that help you find the through line.
Stories Within Stories
We often talk about stories having “sub-plots”. You can apply these techniques recursively. As you explore the details of your system and build a story around them, you’ll often find that some of the components or modules are complex enough to be their own story.
For example, in the Model-View-Controller example, the View is the part the user interacts with directly. Designers work hard to present the Model in useful, compelling ways. This often means that the View can get quite complicated as designers stack on animations, visualizations and transitions. It’s not unusual for the View to contain hundreds or even thousands of lines of code for every line in the controller.
Don’t be afraid to explore these interesting details more thoroughly. If you use the controlling idea and the through line to tie this sub-plot into the overall arc of your larger and more complex story, you don’t have to worry about confusing or distracting your audience.
Learn how to simplify complex things and explain them to others with storytelling techniques.
Storytelling enhances every aspect of your job: debugging, requirements gathering, interviewing, learning new tools and platforms, knowledge transfer, and more! If you’d like to transform the way you communicate, sign up for my upcoming workshop with master storyteller Kevin Allison.
October 19th
1–4PM
Rehearsal Studios at CUBE PGH, 5877 Commerce St, Pittsburgh PA 15206
With less than two weeks left, seats are filling up fast! Get yours now!
Sign up today.
Other “Speaking Technically” articles: Characters and Personification, Failing Upwards, Driving Change
