Technical Blogging as Storytelling

Do you remember the scene in Silver Linings Playbook when our main character portrayed by Bradley Cooper, Pat Solitano Jr, finishes reading his Hemingway novel (if you haven’t, caution, strong language)? I’ve done that. In my mind only, sure. But I have uttered swear words after finishing books, movies, TV series, and even blog posts.

Why? Because I felt like the author broke the promise implicit in storytelling.

Just because we can write whatever we feel like — within reason (although I have seen examples of that going out the window) —, doesn’t mean we should. When creating a piece, we enter into an informal contract with a reader. We ask that reader to trust us as we lead them on a journey. We make a promise that, at the end of it all, we will not have wasted that person’s time. We will wrap up loose ends, answer the questions we raised, and we will, in some way, communicate something useful. In traditional storytelling, the promise may be more to make you laugh, to scare you, to make you think or to just plain entertain you.

To me, a blog post is a story. Obviously, what I write for Corgibytes — a company blog — will be very different than what I write for a personal blog. There are parameters to respect. I see that as being akin to genre. A thriller will read differently than a romantic comedy. Partly because of the topic, partly because of the expectations that come with each genre. That branches out even more, like sub-genres, which would translate to various styles from one company blog to another, even in the same target market, as the posts aim at different target audiences.

So the basic idea of blog posts and stories is the same. We want to communicate ideas. Share lessons learned. Teach something. To do that, we tell a story.

“Except for technical posts. We don’t tell stories in those.” Including technical posts. We do tell stories in those.

The Journey

Just because a post is technical, doesn’t mean it has to be boring or without structure. As an author, you’re still taking someone on a journey. The scenery may involve more code snippets, dev environments, and testing rather than shimmering lakes, colorful trees and breathtaking sunsets, but the process is the same.

A great place to start, as in any story, even in the most technical of posts, is with the quintessential three-act structure.

The Three Acts

ACT I

The journey starts with our hero going about everyday life and dealing with the struggles that come with it. Then, something happens to upset the balance. It’s our inciting incident, a plot point that changes the course of events and sets the story in motion.

In a technical post, this is where you present a problem that you uncovered. You were going about your work day, when suddenly you were faced with an issue that stopped you in your tracks.

It’s fair to assume that your reader is likely to be someone who shares that pain point. Because if they don’t, they’ll probably be moving on to an article that actually speaks to them. So bond with that person who stuck around. You know what it feels like to be in that frustrating or scary situation. Take a moment to let that reader know they are not alone.

At the end of Act I, the hero accepts the mission to solve the problem and enters the journey. Because if your hero walks away, there’s no story. Just like if you had decided to ignore the problem, well, you’d have no blog post. At least not one that will be useful to anyone.

ACT II

Your hero enters unfamiliar territory. The environment contains unanticipated perils, and the hero has to use whatever is available to at least try and stay ahead of the mounting obstacles.

In a technical post, this is where you share all of your wrong turns. Unless you figured out how to debug/fix the code on your first attempt and made it all work perfectly on that first try — in which case congratulations, and I’d like to review the tape on that —, you too struggled to find a good, maybe even great, solution. You made mistakes, you broke some code, you made systems crash. Share these. Help someone else avoid those same dead-end paths.

At the end of Act II, our hero is frustrated. It seems all possible solutions have been exhausted and nothing has worked. Our hero feels like giving up is the only option.

You know that, in the end, you found a solution. So don’t let our hero/reader suffer any longer! It’s time to give them some hope.

ACT III

In Act III, our hero regroups. Reviews all of the failures. All of the wrong turns. And learns from them. Learns what not to do. But now is the time to figure out what to do.

In a technical post, this is where you share your solution and how you came up with it. Don’t be shy. Show your work! Explain why the solution fits and its limitations if there are any. Not only are you helping others by providing a solution, but also you’re giving them a process to try next time they’re faced with a similar situation.

The blog post becomes more than an answer. It becomes a teaching tool.

And, now, in our denouement, having followed this new plan of attack, our hero — and your reader — has vanquished the villain. They’ve fixed the code, set up a new useful environment, tested thoroughly and safely.

They are victorious!

The Epilogue

The epilogue, when there is one, takes place after the story has concluded. It can be a comment or a reflection on the events that occurred.

In technical blogging, this could be additional thoughts. But, even more importantly, I think part of the epilogue is posing a concrete gesture: actually posting the piece. And in sharing your experience with the world, you help out millions of others desperately seeking a solution to that same struggle. You bring joy and peace to their lives.

Ok. Even if you end up only helping out one person and alleviating a fraction of the pain. It’s still worth it.

Also, to keep the actual storytelling from being dry and detached, inject some of your personality in the post. Speak to the reader as you would to your best friend in dire need of your help. Unless your choice of words with your best bud is a little too colorful. Then, picture a small, impressionable child, within earshot.

Just remember. Don’t cop out. Don’t be stingy with your knowledge. Don’t go for cheap tactics to get readers. Be honest. Be helpful. Be generous of spirit. And keep your promise to those readers, whether it be to entertain them, provide them with a workable solution, or teach them something.

Unless you wish to become that author who writes stream-of-consciousness nonsense or click-bait crap that will cause me to go all “Pat Solitano” on you!