Mystery in the Manor (Ep. 4)

The best story is the one narrated by the technical detail itself

In this murder mystery story, you will read about Colonel Mustard, who murdered Professor Plum in the kitchen using a candlestick. The story will first set the scene by introducing the characters and the location. You'll then read about how Professor Plum was found dead in the kitchen. As the investigation unfolds, a bloodied candlestick is discovered. Eventually, the detective uncovers the rest of the clues to determine that Colonel Mustard committed the crime.

Maybe, just maybe, I should stick to technical writing instead of writing murder mystery stories.

---

Spoiler alert • Right, so I'm sure you've never read a mystery book with all the spoilers on the first page. However, most technical articles you read do precisely this.

Does it matter? A technical article is not about entertainment, after all. Don't you just want to have all the facts presented to you in a technical article?

My thesis is that it does matter and that a technical article that leads you through a journey of discovery is more likely to achieve its learning objectives than one that presents the facts outright.

I'll explore this thesis in Breaking the Rules over the coming weeks and months (and years?), looking at what evidence I can find from history and science. But today, I want to focus on how we can add mystery and suspense to a technical explanation.

---

Plot twists, suspense, red herrings, clues • But how can we turn the presentation of abstract technical facts into an exciting plot? I listed four key components of a mystery story at the start of this section. Surely, they don't apply to the presentation of technical detail, right?

This type of narration is what I call narration through technical detail. The best way to explain what I mean is through a demonstration.

I'll use an example from Python programming. Don't worry if you're not familiar with programming. You'll still be able to compare the classic and the narrative styles.

I'll compare two tools in Python that look similar but behave differently. You’ll read two versions of the same content: the "classic" style and the narrative version. You can decide in which order you'd like to read these. So, if you prefer, feel free to skip to the second and then return to the first. The first part of both versions is the same, but they diverge later.

---

— Classic Style —

Let's start with a list of names:

 >>> names = ["James", "Kate", "Mike", "Isabelle"]

The data is of type list, so you can use methods associated with this data type to make changes to the list. You can use the .append() method to add a new name:

 >>> names.append("Max")
 >>> names
 ['James', 'Kate', 'Mike', 'Isabelle', 'Max']

The string with the name "Max" was added to the end of the list names. Notice how the original list has been modified directly when you use .append(). Lists are a mutable data type, which means they can change after they've been created. Therefore, list methods, such as .append(), change the list they act on.

This is not the case for strings, which are immutable. String methods do not change the object they act on but return a copy instead. Let's look at an example using the string method .upper():

 >>> my_name = "Isaac"
 >>> new_name = my_name.upper()
 >>> new_name
 'ISAAC'
 ​
 >>> my_name
 'Isaac'

The method .upper() returns a copy of the original string that's in uppercase and stores it in the new variable new_name. The original variable, my_name, hasn't changed.

---

— Narrative Style —

Let's start with a list of names:

 >>> names = ["James", "Kate", "Mike", "Isabelle"]

The data is of type list, so you can use methods associated with this data type to make changes to the list. You can use the .append() method to add a new name:

 >>> names.append("Max")
 >>> names
 ['James', 'Kate', 'Mike', 'Isabelle', 'Max']

The string with the name "Max" was added to the end of the list names.

Let's explore string methods next. Instead of a list, you'll use a string this time:

 >>> my_name = "Isaac"

One of the string methods is .upper(), which converts all the characters to uppercase. You can try using this method in a similar way to how you used the list method earlier:

 >>> my_name.upper()
 'ISAAC'

Great, it works. But this is a source of a common bug in Python programming. Let's add another line to check the value of my_name. I'll show all the lines of code in this section:

 >>> my_name = "Isaac"
 >>> my_name.upper()
 'ISAAC'
 ​
 >>> my_name
 'Isaac'

The statement my_name.upper() returns the name in uppercase letters. However, when you check the value of the variable my_name, it still shows the name with only the first letter in uppercase.

Compare this to the behaviour of the list method .append(). You use the methods in a similar way, but they behave differently. One changes the object it’s acting on and the other doesn’t. This seems bizarre.

This difference is because lists are mutable data types, meaning they can change after they've been created. Therefore, list methods change the list they act on.

Strings are immutable. Therefore, string methods do not change the object they act on but return a copy instead. To store the result from this string method, you need to assign the value returned to a new variable:

 >>> new_name = my_name.upper()
 >>> new_name
 'ISAAC'
 ​
 >>> my_name
 'Isaac'

The new variable new_name contains the version with all uppercase characters, whereas the original variable my_name is unchanged.

---

Note: I wrote these descriptions for the purposes of this post on Breaking the Rules. I left some discussion points out for brevity, but these don't affect the key message.

You can read another example of a concept explained using both styles in Section 3 of this article.

---

Compare and contrast • The narrative version leads the reader down a different path than the classic one. It starts by treating the string method in a similar fashion to the list method. And at first sight, it seems like they're similar. But the text moves on to present a plot twist. The original variable my_name did not change. The reader is expecting a similar behaviour to the previous example using lists.

It's only at this stage that the narrative version explains the difference and how it's due to the different mutable and immutable properties of lists and strings. This fact has only become relevant now as the reader has just discovered the different behaviour. The classic version states these facts before the result is shown.

---

Edge of your seat • The reader is more passive when reading the classic version of this text. Information is presented first, followed by an example. In the narrative version, the reader's interest is kept active as they discover unexpected results. This element of surprise encourages the reader to be more alert and involved in what they're reading, keen to find out why this result happened.

A reader who's more active and engaged in the material is more likely to understand and retain the concepts. And the surprising elements of the technical narration make the content more memorable.

I won't go as far as to say that narration through technical detail keeps a reader at the edge of their seat, biting their nails. But you get the idea.

---

Afterword • Recently, I looked at the narrative techniques I've been using to categorise them, and I came up with three types:

• Narration through analogies, such as the example in Episode 2.

• Narration through story-framing, as discussed in Episode 3.

• Narration through technical detail, which you just read about in this post.

The names are not catchy, I know. I'll work on it.

Narration through technical detail is the most subtle of the three but probably also the most effective. It's also the one you can use most extensively since it can be applied to all the technical explanations.

---

---

---