The Different Flavours of Narrative Technical Writing

Why I'm using more storytelling techniques in my Python articles

and

Jun 22, 2023

Every Thursday, we bring you original or cross-posted articles on the art and craft of technical writing. This week, enjoy

Stephen Gruppetta

from
The Python Coding Stack • by Stephen Gruppetta
sharing his wisdom on how to craft compelling stories to really make your technical writing shine.

There's a book on my shelves called Principles of Optics. But no one ever uses the book's name. Everyone who knows about this book refers to it as Born & Wolf after the two authors. This is the optics textbook, as classic as it comes. The Shakespeare of the optics world, if you like.

Except that, it's not Shakespeare. This is a science textbook from a different era. Max Born, one of the authors, was a key figure in early twentieth-century physics, especially in the field of quantum mechanics, for which he won the Nobel Prize in 1954. He's also Olivia Newton-John's grandfather, but I digress.

The in-joke in the optics world is that everyone has a copy of this book on their shelves, but no one has read it. My copy is in pristine condition—and over 20 years old. I remember the day I bought it. I was in the shared office I used as a PhD student, and a senior colleague walked in as I unpacked the book: "Ah, you've got that expensive paperweight, too!" The book contains fact after fact and derivation after derivation, an interminable string of impenetrable words.

Technical writing has moved on from this thorough-but-dreary style of writing. But too much of it can still be a bit dull. Does it matter? Isn't the purpose of technical writing to convey accurate facts that the reader can absorb?

Yes. And No. The key purpose is for the reader to understand the topic. So shouldn't a technical article use all the techniques available to help its readers understand the topic as best as they can?

Why not borrow techniques used by fiction writers and storytellers? After all, a novelist's writing is perfected to convey key messages effectively while keeping the reader interested and engaged.

Narrative (from the Latin narrare meaning 'to tell' or 'to relate') — To tell a story or relate a series of connected events

Narrative Technical Writing — Writing about technical concepts using techniques borrowed from storytelling

Spoiler Alert (or Overview of the Article)

We can borrow techniques from storytelling, but narrative technical writing is not fiction. So I can "spoil" the story for you by telling you what's coming. But don't worry, there are still twists and turns in the plot.

Why humans react better to stories than facts: I'll discuss the premise of this story and how we have always thrived on narratives.
My three categories of technical narration: This article is a personal perspective. So I'll try to verbalise the different ways I add narration when writing technical articles. The following sections discuss each category in more detail.
- Narration through analogies: Analogies are a powerful tool to help understand abstract concepts. I'll explore them in this section of the article.
- Narration through story-framing: We can frame our technical article within the context of a story to make it more memorable and more engaging for the reader. I'll look at some examples.
- Narration through technical detail: Are there any techniques used by storytellers we can use directly within the technical content and not just in accompanying analogies and framing stories? Well, I'd hardly dedicate a section to this if I thought the answer was 'no', right?
Using a narrative writing style and language: The language and writing style we use in technical writing is often very different to that found in novels and other stories. But does it have to be that different?

Let's start from page one.

We're All Story Addicts: Here's Why

In this article, I'm writing about my personal perspective on introducing narrative elements into my technical writing. And I'm proposing to borrow techniques from fiction. This doesn't mean I'm making everything up!

Storytelling has been an integral part of all human societies throughout history—and not just as a source of entertainment. Stories have been used to shape societies and how they think.

Homer's poems and the Sanskrit epics reflected and affected the cultural and moral norms in their respective societies and beyond. Biblical stories influenced people over centuries, and still do. The legends of King Arthur and Shakespeare's plays, and more recently, novels such as 1984 and Brave New World, have had important roles in societies questioning their views and norms.

And for many of us, Anne Frank's The Diary of a Young Girl and Steven Spielberg's Schindler's List have brought to life the harrowing nature of the Second World War better than most factual history books ever could.

These are not just stories for entertainment. They're communicating ideas to the reader. They teach us facts or tell us the authors' opinions on certain matters. There must be a reason why stories are a part of every society throughout history.

But there's also a growing body of scientific evidence to confirm that storytelling has a special role in our brains. As tempting as it may be (it isn't!) to hark back to my days as an academic and delve into a lengthy literature review, I won't. (There are links at the end of the article for those interested.)

Stories activate parts of the brain that are not generally associated with language. Therefore, your brain reacts differently when reading stories compared to when you're reading facts. Good storytelling likely brought an evolutionary advantage in terms of enhancing cooperation and social cohesion, learning, understanding, and transmission of knowledge.

Even during REM sleep, which is critical for learning and understanding, our brain dreams by creating stories. We can't escape stories, not even when we're sleeping.

Stories also bring in emotions that can be used to help the reader understand the topic from a different perspective. They evoke mental images in a way that raw facts don't. Stories are also more easily memorable than facts.

And if the purpose of technical writing is to guide the reader to understand and remember abstract concepts, why not use techniques that have worked for centuries and millennia, backed by growing scientific evidence?

The Three Flavours of Narration in Technical Writing

This article is a snapshot of my thinking about this subject. It depicts the current stop on my journey as I experiment with my technical writing. My starting point was in scientific research. There are no stories in journal papers. And I'm not suggesting narrative technical writing should replace the more rigorous scientific writing needed in scientific journals.

But I was always eagerly waiting for the opportunity to break loose from this restrictive form of writing. So, when I started writing Python tutorials and articles, I felt I had already paid my dues and had a licence to experiment.

There are three distinct categories of narration I've been using in my technical writing:

Narration through analogies
Narration through story-framing
Narration through technical detail

As this article is a reflection of how my thinking and writing changed, I'll use examples from my own writing. But there are other technical authors who use narrative techniques. As I'll be writing again about storytelling in technical writing, I'll highlight other authors in future musings about this topic.

1. Narration through Analogies

Using Analogies to Clarify Technical Concepts

The first of my technical narration categories is probably the easiest to describe. Analogies are a powerful tool to explain and understand abstract concepts. They help us visualise these ideas through everyday experiences that we understand well.

As a student at school and university, I recall coming up with analogies when learning science and maths concepts. I've used this tool over many years to help me process the concepts I'm learning.

An analogy is not necessarily a "story". But it can be one. It's always a description of a sequence of events. The analogy often describes everyday items and events, but this doesn't mean it's easy to craft and write. Some of the most powerful descriptions in literature describe everyday occurrences in a way that highlights certain aspects of those items or events that the author wants you, the reader, to visualise more prominently. The same is true when creating and writing a technical analogy.

There are two key challenges when explaining technical concepts using analogies:

Choosing the right analogy
Connecting the technical topics to the components of the analogy

But first, let me give you an example of an analogy I like to use. I'll get to these two points later.

Monty and The Room Analogy

This is an analogy to describe the structure of a computer program in Python and what goes on when you run a program. The analogy has evolved over the years I've been teaching programming. I'll give you an executive summary below, but you can read it in full here: The White Room: Understanding Programming.

It starts with an empty room. The room represents the infrastructure in which the computer program runs. I said it's empty, but that's not quite true. There are some shelves on one of the four walls. And there's a small red booklet on the bottom shelf. This booklet has references to built-in functions, constants, and keywords.

There's also Monty, a friendly avatar who follows your written instructions and gets things done. In many ways, Monty is the personification of the computer program.

When you import a module, Monty leaves the room and goes to the big library in the centre of Python City, fetches a book with the module's name, and brings it back to the room, placing it on one of the shelves.

When you assign a value to a variable name, Monty fetches a box, puts the object inside the box, and labels the box using the variable's name. He places the box on the shelves.

And when you define a function, Monty builds a new room adjacent to the main one, with a door linking the main room to the function room. The function's name is written on a label on the door leading to the function room.

A learner can use this analogy to create a visual image of Monty and the rest of the analogy's components. When they read or write Python code, they can map the abstract code to the clear mental image they have of the rooms, the boxes, the books, and so on. This exercise translates the technical processes that happen in a computer program to concrete everyday actions that we can all easily visualise. Here are some examples:

Abstract concept: Use an existing variable name in the code.
Action within analogy: Monty looks for a box labelled with the variable name, brings the box down from the shelf, and fetches the contents of the box.

Abstract concept: Call a function with one argument. Function returns one value.
Action within analogy: Monty looks for a label with the function name in the main room. He finds it on a door leading to another room. He picks the object referenced in the function call's parentheses (the argument) and walks through the door to the function room, taking the argument with him. When Monty performs all the actions in the function room, he returns to the main room, taking the result from the function room with him.

This mapping between abstract and concrete helps a learner understand what's going on. But it also helps them recall the process later. There's no need to memorise the abstract steps since the story the analogy tells is memorable.

An empty room with shelves. Everything is white — Visualising the empty room with shelves that’s central to the ‘Monty analogy’

Let me return to the two challenges we face when using narration through analogies.

Choosing the right analogy

Finding a good analogy is not easy. It needs to describe an item or event that's sufficiently common. Most of your audience should have experienced this situation and understands it well. It can't be too specific or niche. For example, using a cricket match as an analogy will work for some audiences but will not make sense to many more. This defeats the purpose of the analogy since you're replacing an obscure process that's not clear to your audience with another scenario they don't know much about.

The Monty analogy works well since it talks about boxes on shelves and rooms with doors. They're concepts everyone understands very well.

An analogy can't be too contrived, either. You'll probably lose your audience if you force them into mental gymnastics to link the abstract concepts with the items and events in the analogy. I'll talk more about this in the next section.

Another fine line with analogies is knowing when to stop diving further. No analogy is perfect and will break down if you go into too much detail. This is fine since your audience understands you shouldn't take the analogy literally. But when you reach a certain level of detail in your topic, you may need to stop using the analogy. Don't push too far!

Connecting the analogy's components to the technical topic

The second challenge with analogies is specific to how you present them. When you first introduce the analogy, whether in writing or verbally, you guide your audience into creating a mental picture of the scenario. This is a similar skill to describing a scene in a novel. The author tries to create a clear picture of the scene in the reader's mind, focusing on the things that matter most.

You need to use your descriptive writing skills when writing an analogy to emphasise the key items and events in the analogy. You also need to clearly connect them to the abstract concepts they represent. If you, the author, don't do this, you risk your reader filling in the blanks and possibly making the wrong connections.

For example, in the Monty analogy, the boxes are clearly described as the variables that store objects, which you create using the equals sign in Python. And the variable name is what you write on the label you stick outside the box.

You may have a clear vision of the analogy in your own head. But you want your reader to have that same clear vision.

Let me finish this section with a link to a couple of other analogies I often use when teaching programming:

The first one is described in this article: Functions in Python are Like a Coffee Machine. It describes an everyday object—a coffee machine—and maps its features to those of functions in Python.
The second one uses a story to present the analogy: Understanding The Difference Between is and == in Python: The £5 Note and a Trip to a Coffee Shop.

We'll also return to this last example in the next section about story-framing.

2. Narration through Story-framing

Creating a Narrative Framework for the Technical Content

You can't explain everything through analogies. And even when you can, the description of the analogy is not enough. You still need to write about the technical concepts directly. After all, even if you include narrative techniques, you're still writing a technical article!

Reading technical content is difficult. As authors, we can try to avoid making it harder than it ought to be, but the reader still needs to focus and concentrate as you explain the material. Using a story to frame your technical content can help reduce your reader's cognitive load. This improves their ability to understand and remember the content.

There are two ways in which I frame technical content within stories:

Framing a single example
Framing an entire article

Let's look at both of these methods.

Story-framing a single example

The first one is so important for me that it's part of my technical writing style guide I use for every article I write. It's best to explain this using an example.

Let's assume I'm writing an article to introduce the for loop in Python. I am deliberately choosing a fairly basic topic, if you're familiar with programming, so I can focus on how to present the content rather than the content itself.

First, let's assume this is the example I use:

nums = [2, 4, 6, 8]
for i in nums:
    print(i)

This is not an unusual example. You'll find variations of this in many tutorials. However, it doesn't provide any context. As an author, you must work hard with this example to explain why we need to use a for loop and how the for loop works. The reader must also work hard to follow your explanation and understand.

What if I use this example instead:

team_members = ["James", "Ishaan", "Kate", "Ana"]
for person in team_members:
    print(f"Hello {person}. Welcome to the team")

I've replaced a set of numbers lacking any context with a set of names labelled team_members. Even without further explanation, the reader can already picture a scenario where there is a team with four members. It doesn't matter if the reader pictures a sports team or a team of colleagues; they can see this example within a real-life context.

The for loop itself is framed as code to greet the team. The program welcomes each team member. Clearly, you need to repeat the greeting for each team member, which is the whole point of a for loop.

And if you'd rather have an example using integers instead of strings, then you can try the following:

scrabble_word_points = [10, 24, 3, 14]
print("Here are your Scrabble word points")
for points in scrabble_word_points:
    print(points)

As you can see, you don't need to craft a complex story on the scale of War and Peace. A simple narrative to frame your example is enough to make a difference.

Story-framing a whole article

I mentioned earlier that there are two ways I use story-framing. The second technique is to frame an entire article within a story, not just a single example. The case I'll show you next goes beyond this and frames a series of articles, not just one.

I'm currently writing a series of articles about object-oriented programming in Python. This is not a small topic, so I knew I'd need to write several articles. At the brainstorming stage, I was looking for narratives I could use to frame this series of articles. In the end, I settled on Harry Potter.

I divided the content into seven articles since there are seven books in the Harry Potter series. Each book in the original Harry Potter series represents a year at Hogwarts School of Witchcraft and Wizardry. Therefore, I framed each of my articles as a year at Hogwarts School of Codecraft and Algorithmancy. The students are learning object-oriented programming at my Hogwarts, unlike in the original books where, I'm afraid, programming wasn't on the curriculum!

The main parts of the article still focus on technical Python. The story mostly comes in at the beginning and end of each article. However, the examples I use in the articles are also linked to this overarching narrative. So, we create classes called Wizard and Wand, and we have methods such as cast_spell().

These choices have no impact on the technical aspects of the articles but make the material easier to follow and learn.

Why story-framing helps

Both types of story-framing can reduce the learner's cognitive load, especially the extraneous load—this is the cognitive load brought about by how the information is presented. Here are some ways story-framing can achieve this:

Stories provide context: By adding context to the technical explanation, the reader can understand why and when to use the techniques described.
Stories increase engagement: People engage with stories better than with abstract content. The increased engagement can help the reader maintain a longer attention span and retain the information better.
Stories aid information organisation: The brain needs to process and organise new information. A narrative structure can make this step easier.
Stories provide memorable anchors: A reader must recall the information they learn. Facts aren't easy to recall. The story provides anchors that the reader can use to recall the information.

In the earlier section about analogies, I linked to an article about the difference between the keyword is and the operator == in Python. I linked this article in the previous section as it focuses on an analogy, using a £5 banknote to explain the difference between the two operators. I could have simply talked about a banknote without providing any further context.

However, I also framed this analogy within a story. The story talks about the time I met a friend at a coffee shop. It describes our interactions with the barista and a £5 note we spotted on the floor. The story is not required to make the analogy work. But it strengthens the analogy by emphasising the difference between the value of the note and the actual, physical note through the context presented by the story.

3. Narration through Technical Detail

Incorporating Storytelling Techniques when Describing Technical Detail

The final category is probably the hardest one to describe. It's also the hardest to implement. In this category, we're no longer creating a story in the conventional sense, as we did with analogies and story-framing. Instead, we'll try to make the technical details narrate their own story.

Eh?!

Let me start with an example. I'll get back to what the last paragraph means later.

I'll use the topic of defining functions in Python as an example. And specifically, I'll focus on how variables defined within the function are local variables. Oops! I should have given a "spoiler alert" warning!

I'll pick this up from the point when I'm adding a variable to a function I've just defined. The function is add_numbers_incorrectly(), which tries to add two numbers together but struggles to get the correct answer. This is the code we have so far:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)

Here are two alternative versions of how the article could explain what comes next.

Version 1

The variable result you create within the function is a local variable. This means it only exists within the function and cannot be used in the main program. You can confirm this with the following code:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    
print(result)

This code gives the following NameError:

Traceback (most recent call last):
  File ... line 6, in <module>
    print(result)
NameError: name 'result' is not defined

You need to return the value within the function. Let's add the return statement and call the function to confirm that this change is what's required:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result

result = add_numbers_incorrectly(3, 6)
print(result)

This code gives the following output:

However, note that there is a random component to the value output.

Let's look at the second version before I comment on the first one.

Version 2

Let's test this function to see whether it works as intended:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    
print(result)

This code doesn't work. Here's the error we get:

Traceback (most recent call last):
  File ... line 6, in <module>
    print(result)
NameError: name 'result' is not defined

This error seems bizarre since it's clear that you defined result on line 4, but the code still complains that the name result is not defined on line 6.

Perhaps it's because we haven't called the function yet? Let's fix this:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)

add_numbers_incorrectly(3, 6)
print(result)

You call the function before trying to print the result. However, you still get the same error message you got earlier. This is because when you define a variable within a function definition, that variable is a local variable. This means that it only exists within the function, and it's not available in the main part of the program.

You need to explicitly return the value at the end of the function definition:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result

add_numbers_incorrectly(3, 6)
print(result)

The function now returns the value you get from the bizarre addition in the function definition.

However, when you run this code, you still get the same error you got on the previous two occasions. There's one more part to the puzzle.

The return keyword doesn't return the variable. Instead, it returns its value. Therefore, the variable result still doesn't exist outside the function. However, the function returns the value resulting from the addition. You can assign this to a variable in the main scope of the program:

import random

def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result

result = add_numbers_incorrectly(3, 6)
print(result)

Now, you create a new variable result in the main program and assign the value returned by the function. Finally, you have an output printed by this code:

Note that there is a random component to the value output.

Comparing the two versions

I'm sure I was biased and made less effort with Version 1 when I wrote these! But this won't change the key points.

In Version 1, I give you, the reader, the key result right away: variables created in a function definition are local variables. I still show you the error message, but you were expecting it.

The final segment in Version 1 adds the return statement and the correct function call. They style is to tell you what you need to do and then show you the code. These paragraphs in Version 1 show you how returning values from functions should be done. What's wrong with that?

Let's look at Version 2. I don't tell you what the problem is right away. In fact, I don't even tell you there's a problem. I write some code and run it. This is when you discover there's an error. You're now curious why this didn't work. So I offer a key bit of information: variables defined in function definitions are local variables.

However, the following code snippet still doesn't show the whole truth. I add the return statement in the function and nothing else. But you still get the same error. You're puzzled. Like in a good murder mystery story, you solved a part of the problem but discovered there's more.

So I guide you to look for the next clue: the function isn't called. I add the function call to the following code segment but without assigning its return value to a variable. I'm slowly revealing the whole truth, bit by bit. You, the reader, are more aware of what you're reading since you're surprised by the results. It's not what you're expecting. You're not reading these paragraphs passively, just absorbing information. You're engaging with the content, trying to figure out what's still missing.

Finally, I have the final reveal—assigning the return value to a variable.

In the first paragraph of this section, I wrote that "we'll try to make the technical details narrate their own story". Version 2 creates a narrative through the way it gradually adds bits to the code without revealing the whole truth straight away.

I'll reuse the analogy of the murder mystery story. Version 1 starts by telling you who the murderer is and then explains how the events leading to the murder unfolded—that's not a fun murder mystery to read. Version 2 doesn't spoil the story and has twists to the plot. This is an example of narration through the technical detail itself.

Bonus Content: The Narrative Writing Style

There's a fourth narrative pillar I use in my technical writing. This focuses on the language style itself. Read a typical technical textbook, such as Principles of Optics, and compare the language used with that in a good novel. The style of words used is different. So is the sentence structure. In a story, the author can use sentences of different lengths to set a rhythm to the text, for example. And punctuation marks, well, punctuate the reading. As an author, you can use these tools to guide your reader through the article at your chosen pace.

People default to a narrative style when talking informally, such as with friends. We've already seen how we've evolved to prefer narration and storytelling. When writing technical articles, I try to picture myself sitting in a quiet, cosy coffee shop with a couple of friends.

Imagine I meet a friend over coffee who happens to be learning to code. After a bit of chit-chat, he asked me to explain functions to him. Here's the conversation we did not have:

"Joe, functions are an important topic in programming. It is possible to create blocks of code that can be reused flexibly.
Over the next 30 minutes, I'll teach you:
One. How to define a function
Two. How to include arguments
Three. How to return values
By the end of this half an hour, you'll be able to define your own functions."

You wouldn't think it's strange if the text above was the introduction to a written technical article. But it's not very plausible in the context of a chat with a friend over a hot cup of coffee.

Why not shift our technical writing further towards a friendly and relaxed conversational style? Of course, there are still differences between a written technical article and a casual chat. But that doesn't mean we can't use a more conversational tone and style when we write. This helps our readers engage with the content, understand it better, and be able to recall it in the future.

Final Words

It's not always easy to deviate from the norms. Technical writing often sits closer to the formal, academic writing end of the spectrum of writing styles. Over the years, I have questioned this style, at least for my own writing. If the purpose of writing a technical article is to engage the audience and make it easier for them to understand and recall the key points, why not use the tried and tested techniques that storytellers have been using for millennia? Don't we share the same aims as creative writers?

I'm not advocating that everyone's technical writing should be steeped in storytelling. Not all my articles are stories, either! And when I use storytelling techniques in an article, I'm cautious not to overdo it.

Of course, storytelling can be used to mislead. There are plenty of examples of this in history. But this risk is much lower when writing about technical content. If you trust the author, you can let them take you on the journey they crafted for you.

And I'm still exploring and experimenting with what works and what doesn't, testing the boundaries. This article is a snapshot of my current views on narrative technical writing. Like all my views, they can, and likely will, change over time.

I plan to write regularly about my thoughts, views, and experiments in narrative technical writing. There's a lot more I'd like to say about all the topics I introduced in this article. So, stay tuned!

Should you use narrative techniques in your technical writing? That's not up to me to tell you. We all have our own style, and storytelling doesn't necessarily suit everyone. If you choose to go down this path, you must be ready to break some of the classic rules of technical writing. Not everyone will be comfortable with this. Personally, when it comes to technical writing, I'm happy to be breaking the rules.

The Tech Writers Stack

Discussion about this post