The Story So Far (Mid-Season* Review)

Are you back from your holidays? Catch up with what you've missed

Once upon a time, I wrote Once Upon an Article, the pilot episode. And by "once upon a time", I mean just over two months ago.

One pilot and ten episodes later, it's time for a mid-season* review. This is also an opportunity to catch up with what you missed while you were sunbathing on the beach or trekking in the countryside or whatever else you were doing on holiday.

* And when I say "mid-season", I don't really mean the middle of a season. Or the middle of anything, really. But it sounds cool.

---

Understanding • What's the purpose of a technical article? This may sound like a silly question to ask. But an ongoing process of answering this question is the key to modern, good technical writing.

And the answer to this question has changed over the decades and centuries, too. In a previous era, the technical article was more focussed on the author. The writer had knowledge they wanted to make public. The article or book was the result of the interaction between the author and the subject matter they're writing about. Traditional technical articles are a reflection of their author's knowledge.

Did you spot what's missing?

The reader.

Technical articles ought to focus on the reader rather than the author. They aim to ensure the reader understands the topic they're reading about. And there's been a steady shift in this direction over the years.

---

Stories • Traditionally, we don't associate technical writing with stories. But once we shift the focus to helping the reader understand, storytelling becomes a tool we should use.

I haven't written much about the science of storytelling yet. That will come soon. But I have written about different aspects of narration I've been experimenting with.

The first is narration through analogies. Crafting the perfect analogy is not easy. I wrote about helping the reader see an analogy in Whizzing Through Wormholes (Ep. 2). The process of visualising the analogy is an important aspect of learning through analogies. An analogy also needs to represent a situation that is well-understood by everyone.

Then I wrote about when analogies don't work in The Wrong Picture (Ep. 6). A bad analogy is probably worse than no analogy at all.

The next technique is narration through story-framing. I've often used this technique in my articles on The Python Coding Stack. The technical content is framed within a story to get the reader in the right mindset, ready to engage with and absorb the content. Episodes 3 and 9 dealt with this topic: Frame It (Ep. 3) and Frame It • Part 2 (Ep. 9).

The third area I've been exploring is probably the hardest and most subtle of these key techniques. In narration through technical detail, there's no story to frame the content and no analogy. However, the techniques used to make stories more engaging are used to deliver the content in the article. You can present the technical detail using twists and turns, suspense and a bit of mystery, revealing information gradually. I wrote about this technique in Mystery in the Manor (Ep. 4).

Another technique storytellers use well is to control the pace and rhythm of their delivery. This technique can help your reader engage and maintain focus when used well. I covered this topic in The Rhythm of Your Words (Ep. 8).

In A Near-Perfect Picture (Ep. 7), I explore the idea that the final article is a sample of the ideas we have in our heads. The better the article, the higher the sampling—this means the reader will understand your vision of the topic well. But if this conceptual resolution is low, the reader may get a fuzzy idea, just like a poor-resolution picture doesn't convey the image it's meant to represent.

I promised to write more about the science behind storytelling and how it applies to technical writing soon. I started tentatively exploring this in The Broom and the Door Frame (Ep. 5). And the very first episode also looks at how the brain can act in strange ways, and we can use this to our advantage when helping our reader understand a topic: Sharing Cupcakes (Ep. 1).

Another challenge is knowing when and how often to use these techniques. We can't use them all, all the time. This is also a topic I'll explore further in future Breaking the Rules posts.

---

Right. Review over. And you're all caught up now! There's a mid-season* break next week, so there's no article next Wednesday as I work on the next batch of articles. It will be back to the standard articles from the following week.

---

Afterword • Way back in the pilot episode I wrote:

This is my journal. A place for me to write down my ideas on technical writing, to jot down things I read in books, articles, and some research papers too, and how I interpret what I read in the context of communicating about a technical subject.

And this remains true. I'm glad some of you read my ramblings! But unlike my other Substack, The Python Coding Stack, which at 1,000+ subscribers is growing fast, I don't mind if no one reads the posts on this Substack. Writing it is what matters most to me!

---

---