Frame It (Ep. 3)
You can't replace the technical content with a story. But you can frame it within a story.
I'll let you in on a little secret. I don't really like breaking rules.
And there's my "street cred" as the author of Breaking the Rules gone down the drain!
But if I do break the rules, I really have a strong reason to do so. And the biggest transgression I deliberately make these days in many of my articles is at the beginning—the opening paragraphs.
Story-framing • I'll get to the opening paragraphs of my articles shortly. Let's have a bit more honesty first. This substack is all about narration and storytelling in technical articles. But the technical detail is still the star of the show. We can borrow many techniques from storytelling to soften the hard edges of the article's technical sections—and I'll write about these in the future. But we can't replace the technical content with a story.
What we can do is frame the technical content within a story. The best way to explain this is through an example. I've been experimenting a fair bit with this technique recently.
Earlier this year, I decided to write about object-oriented programming. This is a topic that sits deep in "intermediate" territory. It's one of those topics most people don't get the first time round. Or the second.
This is a perfect topic to frame within a story since the technical detail is not straightforward. A learner needs considerable mental effort to follow this topic. After considering a number of options, the winning theme was Harry Potter. And of course, that meant the series was going to be seven articles long—one for each year at the school, just like the actual books! But in my version, I tweaked the school's name to Hogwarts School of Codecraft and Algorithmancy.
The introduction • And where's the best place for the story-framing? The introduction of an article, of course. But this takes us on a collision course with the rules and guidelines for writing a classical technical article. Most technical-writing guides will tell you the introduction is the place to introduce the technical topic and outline the article and its learning objectives.
There can only be one "first paragraph". Something has to give way.
You probably know which side of this divide I lean towards. I'll show you examples of opening paragraphs from the articles in the Harry Potter series shortly.
But this doesn't mean I use story-framing every time I write an article. It's a tool. It's great to have lots of tools but it doesn't mean you should use all of them all the time. There are times and audiences that are more suitable for story-framing than others. It's fair to say that I rarely (never) write the "classic-textbook style" introduction to a technical article but I don't use story-framing in all my articles either.
Here's the opening paragraph of the first article in this series:
Mr and Mrs Dursley, of number four, Privet Drive, were proud to say that they believed the classic way of computer programming was the one and only path to mastery, thank you very much. They were the last people you’d expect to be involved in anything strange or mysterious such as the perplexing world of object-oriented programming, because they just didn't hold with such nonsense.
Within the perfectly disciplined walls of their home, mentioning such peculiar concepts was strictly off-limits. Little did they know that the seemingly bewildering universe of innovative and efficient programming practices would not be so easily warded off and would soon unexpectedly intertwine with their seemingly normal lives.
The introduction to the article goes on to explain that Harry Potter is about to start studying at Hogwarts School of Codecraft and Algorithmancy, a school that teaches object-oriented programming to young coding wizards.
The rest of the article focuses almost entirely on the technical concepts of object-oriented programming. The story is mostly contained to the beginning and end of the article. There are a few passing references to the framing story within the article, such as this sentence:
The professor strode in, cloak flapping with every stride. He flicked his wand, and bits of chalk started screeching on the blackboard:
However, the words written on the blackboard referred to Python coding concepts and not wizarding matters. Story-framing does not mean that your entire article is a narration of a story. This is still a technical article, after all.
Here's the opening paragraph of the third article in the series which talks about methods, a key topic within object-oriented programming:
The Hogwarts Express thundered through the landscape, the rhythm of its powerful engines setting the tempo for the excited conversations within. The third-year compartment hummed with a different kind of energy - an air of contemplative excitement. Each held a thick tome, its platinum lettering shimmering with subtle magic:
Secrets of Sorcery: Defining and Deploying Methods
Year 2 had been a fascinating journey through the foundational elements of object-oriented programming in Python, mastering classes and data attributes. But as the train sped towards a new term, the true spellbinding journey was about to begin. With the turning of each page, the third-years would not only become observers of the magic within Python, but also the wizards behind the curtain, creating and controlling their own spells in the form of methods. The Hogwarts Express was not just ferrying them to school, it was hurtling them towards an exciting new chapter of their magical education.
The "quality" of the prose is not important. No one is expecting the narrative text to rival that of professional fiction authors. In fact, I deliberately wrote these paragraphs to be a bit over the top.
Why? When? • There are three questions I want to deal with: What? Why? When? This post so far dealt with what story-framing is.
I promised to keep posts on Breaking the Rules relatively short. So I'll defer most of the discussion about why and when to use story-framing to a future post. But here's a preview.
When you start an article with a story, you can no longer start by introducing the technical topic and provide an outline of the article. There can only be one beginning! The classic introduction serves the purpose of telling the reader why the topic is important and what to expect in the article. Sometimes, this is relevant and important. But is it always necessary? Do you ever skim through a "classic" introduction when reading an article and jump straight to a later section? And as a reader, is it always helpful to know the key topics you're going to read about even if you don't understand what those key topics are?
Am I being a heretic?
Maybe. Remember that I'm writing Breaking the Rules to help me explore these ideas. I don't have answers. But I have many questions. Don't I?
But stories trigger different processes in the brain. There's research about this from recent years, which I'll write about soon. This is why I use story-framing. Hopefully, I'm tapping into a different part of my reader's brain which will help them understand and recollect the material.
Let's get back to my series on object-oriented programming. My ideal reader for these articles is not the learner who's never heard about this topic and is reading about it for the first time. This reader can still enjoy the articles and understand the topic, but I'm not writing specifically for him or her. Instead, I'm writing for those who already know about the topic, have studied it in the past, but still find it challenging. And when it comes to object-oriented programming, this group of people is large! My ideal reader doesn't need the bland introduction to the topic. They've read it elsewhere already.
Story-framing also works best when a reader is already familiar with the author's work and is willing to trust them with the learning process.
Darn! I've gone over a thousand words. Sorry. I'll carry on next time. Goodbye.
Afterword • I've said this before but I'll repeat myself: Breaking the Rules is not a manual for writing technical articles. It's where I'm keeping notes about my thought processes as I decide what to try and as I research stuff to justify or disprove my hunches.
And I'm not trying to write the perfect posts. These posts are raw. Yes, I do read and re-read them before I post. Of course I do. But I'm not trying to edit them to perfecton [see what I did there?]
