Engineering

Writing better technical blog posts with the story spine

Headshot, Ben Ogle
By Ben Ogle

Humans are drawn to storytelling. Learn how we use narrative structure as a framework to write our technical blog posts on the engineering team.

Arrow iconBack to all articles
Writing better technical blog posts with the story spine

Here on the engineering team at Anvil, we have a blog post rotation. Every two weeks, someone on the team writes a post for the engineering blog. The prompt is open ended: write about something developer-related that is interesting to you. It can be as long or as short as you want, it just needs to share some of the author's interests and expertise. We often write about things we built or problems we solved, usually something fresh in our minds.

If I've learned anything from the team writing these posts, it's that writing is hard. No surprise, right? On top of that, it's surprising how difficult writing is, even when you know what you want to say. Where should you start? How should you structure the post? What should you present first? What terms and concepts should you define? How much detail should you add? How do you nail a specific voice? Is this even interesting? Why not?

In every post, there are a million directions you could take. The options are limitless and limitless options can be crippling. Writing is frustratingly the kind of activity where more time spent does not necessarily result in better output. For example, in this very post, I have restructured the whole thing at least three times. Is the third pass better than the second? Did I learn anything in the second pass that is helping me in the third? I'm not sure. I know what I want you to know, but I don't know how to tell you.

It is a struggle every two weeks when we write our next post. How can we ease the pain? How can we make both the writing easier and the content more interesting?

This is your brain on stories

Think back to the last great movie or TV show you watched. How did you feel afterward? It may have moved you, inspired you, or frustrated you. Maybe you felt a change in perspective or a connection with the characters. No matter the specific emotion, you probably felt different afterward, at least for a short period of time.

Humans are wired to respond to stories. Stories change our brain activity and release oxytocin: the "love hormone", but also the whole-bunch-of-other-feelings hormone. Turns out these brain chemical changes have all kinds of benefits for someone trying to get their point across.

Narratives that cause us to pay attention and also involve us emotionally are the stories that move us to action. - Source

[M]y experiments show that character-driven stories with emotional content result in a better understanding of the key points a speaker wishes to make and enable better recall of these points weeks later - Source

If you create a good story that resonates, you can motivate your reader, make them feel connection, and have them remember your ideas. A win on all fronts.

Narrative structure

Okay great, humans love stories, but how does one write a good story? Turns out all stories follow some kind of narrative structure—basically just a story framework.

Every story can be broken down into one of these structures, all movies, novels, TV shows, everything! While there are a lot of narrative structures out there, most western stories tend to follow a structure that can be reduced to three-acts.

  • Act I: Setup
  • Act II: Problem
  • Act III: Resolution

The three-act structure feels pretty straightforward: just state your prior situation, your problem, then your solution. From the perspective of the writer, though, it feels like there is still too much wiggle room. Finding Nemo and The Godfather both use this three-act structure, but are pretty different, wouldn't you say?

For a blog post, it'd be nice to have some better guardrails, more focus could make the writing a bit easier.

The story spine

The narrative structure we've found easiest to map on to a blog post has been the story spine. It fits within the three-act structure, but comes in an easier-to-digest format:

Once upon a time there was blank. Every day, blank. One day blank. Because of that, blank. Because of that, blank. Until finally blank.

I came across the story spine in improv classes I took many years ago. The instructor would go around the room and point at each person to add onto the story. We'd start with something simple like, "Once upon a time there was a black cat." Then by the end, the cat would have been through fighting evil space aliens on a planet 100 lightyears away, narrowly escaping capture and eventually saving the universe.

Because of that, blank lead to twists, turns, tension, and color in the story, ultimately making the story interesting. After the exercise, the entire class would be enthralled, giggling, and joking about parts of the story. That oxytocin, you know?

How we use the story spine

Most of the time, our engineering blog posts fall into the bucket of how-to posts. How-to posts seem hard to write in story form. Stories have characters. Should we write about Charlie the cat who needs to learn JavaScript? Not necessary! How-to posts already have two natural characters:

  1. The writer, who struggled, but courageously found a solution to some age-old problem and wants to tell the world about it.
  2. The reader, who has not yet discovered this solution and is living a life of pain.

With a how-to post, it's temping to jump straight to the solution: "This is how you use technology X." But then the reader misses out on the context. Why should they care about technology X? Instead, we can use the story spine with ourselves, the writer, as the character to walk the reader through our experience:

  • Here's what I was doing.
  • But then I faced this problem.
  • The problem was painful in these ways.
  • We went looking for solutions, here's what we needed in a solution and why.
  • We considered some solutions. They didn't work for us, here's why.
  • In the end, we used solution. Here's why, and how it benefits us.
  • Here's how we set it up and how you can too.
  • Now the world is shiny and we are in a better place because of the solution.

This path with take your reader from problem, through discovery, and ultimately to your glorious solution. With the little narrative, the reader will have a better understanding of why you made the decisions you did, and what options were considered along the way.

Added color with story shapes

Another dimension you can fold into your writing is "character fortune" though Kurt Vonnegut's story shapes. He charts stories by the main character's fortune over time. Vonnegut identified eight different story shapes, then subsequent research has been done to bucket all stories into only six basic shapes.

By far the most common shape is Vonnegut's "man in hole" shape. The main character gets into trouble, makes their way out of trouble, and ends up better off than where they started.

Kurt Vonnegut's man in hole story shape Man in hole story shape

"Man in hole" is the basis of numerous iconic movies and books like the aforementioned The Godfather and Finding Nemo, but also Monsters Inc., The Hobbit, the Wizard of OZ, and a million more. In movies, it is the most commercially successful story arc of all time.

It's not only suited to big-budget movies, though. It turns out this arc is also a great structure for a how-to blog post. It works along side the story spine and within a three-act structure. A triple whammy indeed.

In the man-in-hole, story-spine, how-to world, you were minding your business, then, all of a sudden, BAM!, a problem arose. (Oh no!) You struggled a little and tried some things that didn't work. In the end you found a solution and implemented it. Here's how the reader can do the same. Now you are in a much better situation and live happily ever after.

Oxytocin, understanding, and retention of your ideas are yours for the taking. Great job.

The end

We certainly did not invent using some amount of storytelling in blog posts. Stories have been used to transfer knowledge and catalyze change since the dawn of human language, and evidently, the campfire. Business people have been using stories as a tool to convey ideas and motivate forever—Richard Branson believes entrepreneurs must be great storytellers to be successful.

Our team has often struggled with conveying the "why" and fleshing out a post beyond steps to implement a technical solution. Storytelling felt like a fix. The challenge for us was learning how exactly to apply a narrative to our own writing.

Going back to a question at the beginning of this post: how can we make both the writing easier and the content more interesting? We now have a bit a framework to limit endless choice, making the writing easier, and the narrative journey helps add color.

Structuring posts with the story spine has been working for us. We're better off for it. We have, in a way, crawled out of the hole.