Technical Writing: A Developer's Guide to Storytelling

When I went to college, I wanted to be a Math major. Calculus II wasn’t offered my first semester, so I took British and American Authors instead. I have always loved reading, and to be able to talk about stories and share that experience with others made it a natural fit as my major. That chance class led to my ten years of teaching college English before coming into tech. Although I enjoyed reading novels and stories, I didn’t see the practicality in creative writing until I started learning how to write screenplays. That’s when I dove into The Writer’s Journey by Christopher Vogler and learned more about why we tell stories, why we want to hear stories, and the connections we make through storytelling. And then suddenly I saw stories everywhere.

As I started teaching Technical Communication, I saw a lot of examples of technical writing that hadn’t seen the value of storytelling. In fact, my students probably would’ve called them “dry,” “boring,” or “personality-free.” But that doesn’t mean that technical writing should be that way. Using storytelling in technical writing can actually enhance the effectiveness of your writing and help your audience to better comprehend and remember your content.

Why should we incorporate storytelling?

In my last post on Technical Writing, we covered the basics. Adding storytelling makes your writing memorable. Storytelling, at its core, is about sharing: sharing your experience, your knowledge, the things that have inspired you. When we share stories, we’re inviting people to participate in the experience, and that’s why stories are so impactful. They allow us to relate to each other, better understand concepts, and acknowledge the voices of those around us. Because stories encourage personal connection, they’re an effective method for engaging an audience and helping them to remember the content we’re sharing.

If we look at this from a neuroscience perspective, storytelling is effective for two reasons:

1. Humans are hard-wired to respond to storytelling. Our brains light up when we hear stories, which creates the connections we need to remember them.

2. Oxytocin - a neurochemical that helps us to feel connected with others - is released when we hear and connect to stories.

It should be no surprise, then, that storytelling helps to connect us to our audience.

According to Paul J. Zak in Why Your Brain Loves Good Storytelling, “When you want to motivate, persuade, or be remembered, start with a story of human struggle and eventual triumph. It will capture people’s hearts – by first attracting their brains.”

How to Storytell Effectively

We should think of storytelling as a decoration for our writing. Too much decoration and the reader won’t be able to see the main point or will get frustrated trying to find it and quit reading. Too little storytelling and your reader is less likely to be invested. Have you ever landed on a blog post for a recipe but the writer tells you the whole history of their grandma’s kitchen before getting to the actual recipe? That is not what we want in our writing. We want to grab the reader’s attention with the story, but make sure we’re not waiting to long to get to the point. And that means knowing your audience and the purpose of your writing.

Audience

In the last post, we covered audience, but it’s important to note that which story you choose will largely depend on your audience. If you think about who your audience is, you can more effectively choose which story or example to tell. For example, if you’re writing for a general audience, you’ll need to choose a story that most of the readers can relate to. I have a talk on mentorship where I look at the mythological journey of the hero and the impact of the mentor. My go-to references are to Lord of the Rings, Star Wars, and Harry Potter and the mentors the heroes find in Gandolf, Yoda, and Dumbledore. They’re popular enough that I get broad understanding and also the connection that those characters have with readers.

Purpose

We should never tell a story for the sake of telling a story. We gain reader trust by giving them a meaningful story that enhances the writing and illuminates our main ideas. It should be like a piece of thread that fits into the pattern and helps to hold the cloth together. In my mentor talk, I don't just name drop the movies and mentors, I still connect it to the purpose of the talk and provide context for the examples and explanation of how those paths to the mentors relate to paths we can create for our teammates, mentees, and people coming into tech. One trick to determine if the story contributes to the purpose of your writing is to remove the story and see if your writing loses meaning. If it does, chances are you’ve used the story well.

Ways to Implement Storytelling in Your Writing

Depending on the type of writing you’re doing, the approach will vary. For example, it’s more natural to see a story integrated in a blog post. We expect this in many of the blogs we read. However, we might not expect it from technical documentation or in user manuals. Here are some options for using storytelling in your writing:

Hook: The hook is usually the beginning of the writing, in the introduction - the first paragraph. This is where you want to pull the reader into your writing and the journey you’re going to take them on. Let the reader connect through a story in your opening. If you're writing about a coding concept, you might begin with where you first learned the concept or the first time you used it well.

Examples: If you’re working on technical documentation, storytelling throughout your writing might not seem natural, but if you’re providing examples, this is a great place to introduce the example with a story or to use the example to tell a story. Choosing examples that are meaningful to your audience encourages a more personal connection.

Response Elements: If you’re writing a technical document and conclude each page with a knowledge check, a way for the reader to engage, or an element that asks the reader for a response, you have an opportunity for adding micro-stories or elements of storytelling to engage the reader.

Gamification: Technical writing can be fun too! Look at the document as an opportunity for taking the reader through a journey, or providing a gamefied learning experience. You can make them the hero in the story as they make the journey through documentation.

Theme: When I was writing a lot of Cypress tests, I would frequently name things after characters from the tv show Parks and Recreation. In a sense, I wasn’t telling a story, but I was bringing in storytelling through my references. Beyond pop culture, other themes for writing can be derived from shared identities, cultures, and communities.

Visuals: The Henrik Ibsen quote "A picture is worth a thousand words" tells how powerful images can be. Images can be woven into your writing and provide an opportunity for visual storytelling. Kevin's post on "Building a Live Transcription Badge with Deepgram", is an introduction to the video with essential links. However, if you look at his incredibly popular tweet that he references, you can see the added value of the initial short video.

Writing, of course is a skill learned on its own aside from technical knowledge. One of my favorite essays on writing is Anne Lamott's "Shitty First Drafts" from Bird by Bird because it captures the process of writing drafts and making changes so well. I first read the essay when I was doing my undergraduate degree, and I taught it to my undergraduates when I was still teaching. When you're incorporating storytelling into your writing, it will be a process. You'll have to decide what story you want to tell, how to tell the story, and where you want to tell the story. And then you'll evaluate if you've chosen the best path for the story, if you need to cut it down, if you've missed the purpose and connection. It's worth it though. Next week, we'll continue diving into finding your writing voice when I cover honesty and ethics in our writing.

If you're enjoying this series, be sure to check out the Twitter Spaces we're doing by following us on Twitter at @DeepgramDevs.

If you have any feedback about this post, or anything else around Deepgram, we'd love to hear from you. Please let us know in our GitHub discussions .