There may be many reasons for this. One of these reasons is the order in which the author presented things or actions in a sentence. We may find it harder to read a sentence if this order doesn’t match the natural order we see and think about things.

In this short-ish video, I show you an example of an edit I made as I was working on my latest Python article.

And they're three different publications.

The Professional One • The Python Coding Stack • The first Substack I started is The Python Coding Stack. It's also my main one. This is my professional publication. My day job is to teach and write about Python. I have written textbooks, contributed to several leading publications in the field, and I also write on my own Substack. This is my elite-level output in my field of professional expertise.

I published over 100 full-length articles on The Python Coding Stack in just over 2 years. There are now almost 6k subscribers, including a few paid subscribers. I gain about 5-10 new subscribers each day.

And each time I publish, I get between 3k and 10k views, sometimes more, since Google often serves these to searches, and some get featured in Python newsletters.

I spend a lot of time on each article. A lot. I go through all my writing stages: initial idea, thinking about how to frame the topic, working on the code I plan to use and then re-arranging it based on my key didactic principles, writing the first draft, several technical, didactic, and language reviews, generating the properly-formatted code snippets to go in the article, transferring the draft onto the Substack platform and several stages of finishing touches.

As I said, each article takes a lot of time to prepare.

And I publish regularly. I don't adhere to a fixed schedule, but I currently publish around 2-3 articles per month.

The Thinking One • Breaking the Rules • That's this one. This is not entirely unrelated to the first one. I've been an educator throughout most of my working life, either as my main activity or as a secondary role. I had plenty of time to think about how I communicate with learners, research existing studies, and apply my theories.

And this Substack is a means to put my thoughts about effective communication when teaching in black (virtual) ink on white (virtual) paper. My primary profession is to teach Python. But the contents of this Substack are relevant to my primary profession. So, this Substack is a meta-Substack, in the sense that I write about what makes me good at my primary job, which is teaching Python.

I have also written a book on this topic and set up a community for like-minded communicators and educators, but this is a secondary professional activity.

I don't publish as often here–indeed, I haven’t published a post for a while. And I have about 250 subscribers. I only get a new subscriber from time to time. Writing a Breaking the Rules post is quicker than writing for The Python Coding Stack–a lot quicker.

The Hobby Accountability One • Back on the Track • The third Substack focuses on a hobby, a hobby I'm returning to after a 25-year absence. I've returned to track and field athletics as both an athlete and a future coach. The Substack is a place to write what I'm learning as I read books about biomechanics, training methods, drills, how to deal with an ageing body, and so on. It's also a way to keep me accountable. Returning to training on the track when the body is no longer in its youthful prime is hard, and having my experience out there in public helps ensure I don't give up.

Back on the Track is very new–it's a few weeks old. I'll publish whenever I have time to write. It's essentially a personal journal and notebook, a record of what I'm learning and what I'm trying out.

I'm not a complete idiot when it comes to the science and practice of track and field athletics. I was very interested in the academic side of the sport when I was first an athlete in my youth. And I'm learning things again now, including the latest research that didn't exist 25 years ago. But I'm not an expert. I'm not writing articles on this Substack from the point of view of a subject expert.

I have 16 subscribers. Some are family! And some of them probably subscribed just to support me, as they know me from my Python work.

Any Similarities? • Yes. I started writing Python articles before starting The Python Coding Stack, as a way to clarify my understanding of specific topics. As one of my favourite educators, Richard Feynman, once said, "If you want to master something, teach it." And writing Python articles was one of the ways I could do this.

And I still do. Even when I write about topics I know well, I still feel that my grasp of the details moves to a new level when I write a new article about it.

And I write about narrative technical writing and track and field for the same reason–to understand the topic I write about better.

This desire for a better understanding is why it's important to write with a learner in mind. Too many educators communicate as if they're talking to themselves–we've all had that University lecturer who no one understood! If they understand what they write or say, it seems good enough for them. But having to explain the concepts to someone who doesn't have the same grasp of the topic is where the magic happens. You need to think of the right words, the right analogies, the right examples…and that's the process that leads to deeper learning.

So, it doesn't matter whether my audience is 1, 16, 250, or 6,000. I write the articles I would want to read. The primary reason for writing is a selfish one: to learn. I don't need anyone else to read what I write.

And it's hard to keep this mindset when a publication picks up pace. Each time I publish an article on The Python Coding Stack, I know that 6,000 people will receive an email with my tutorial, and possibly even more will read it. But the way I cope with this is to accept that my ideal reader is someone like me, who likes the same learning style. If I like an article, then my ideal reader will, too. I don't want to change why I write and how I write because I have an audience to please.

I once shared publicly that "I don't care what my audience thinks". In hindsight, I realise why that statement, when read out of context, seems irrational, arrogant, and stubborn. But hopefully now you know what I mean.

Get a copy of my latest book, Breaking the Rules. Available in paperback or ebook…

Get Your Copy Now

I don’t publish too often on this Substack, but you can stay up-to-date and make sure you get each post by subscribing below…

Subscribe now

Today, I published my latest article on The Python Coding Stack. It's not an extensive tutorial about a fundamental topic in Python. Instead, it deals with a relatively minor observation about a useful but hardly exciting Python tool.

As I planned and wrote the article, I kept a record of all the steps, thought processes, considerations, deliberations, and decisions that led from that initial spark of an idea to hitting the Publish button. This post presents this process.

I'm very aware that many of my Breaking the Rules readers aren't Python programmers. Python knowledge is not required to follow this post. I'd also recommend reading the main Python article before continuing with this post. It's not a long article, and you'll follow most of it even without Python knowledge. Here it is: https://www.thepythoncodingstack.com/p/counting-in-python-list-count-how-hard-can-it-be

WTW • Every article starts with the WTW stage–What to Write?

I was recently teaching a live session, and the discussions led to a somewhat unexpected result. A straightforward command to count how many times an item appeared in a collection seemed to give the wrong count.

The discussion leading to the reason behind this apparent counting error and how to fix it was revealing, and it showcased key aspects of how Python works behind the scenes.

Soon after the live session ended, I jotted down this thought in the Ideas column on the Kanban board I use to track my articles. This is the leftmost column on this board. It's where all articles start.

Summary of the technical topic: The Python instruction .count() is linked to a list of items, and it returns the number of times a specific item appears in that list. But when the items in the list are of a type defined by the programmer, Python may not know how to group similar ones together. So, it may fail to give the "right" answer.

Brewing • The brewing stage is when I develop my ideas. This is when the article takes shape, even though I rarely write a single word down during this phase.

On the face of it, the topic for this Python article is rather dry. It deals with counting objects and why Python sometimes "gets it wrong." [Spoiler alert: it doesn't.]

But there's always something interesting if you look deep enough. This is the direction the discussion took in the live session that led to this article idea. This topic felt like one that could benefit from story-framing. [More on story-framing in chapter six of the Breaking the Rules book]

But it's also one that could benefit from narration techniques applied directly to the technical details. [And there's more on narrating the technical details in chapter seven of the Breaking the Rules book]

Deciding early on what narrative techniques I wish to use is important as it gives me a good idea of what type of article it will be. In this case, story-framing was going to be the primary narrative tool. That means I need to find a story to fit the main point of the article. The story isn't just a bit of fun on the side. It needs to help communicate the technical content.

I let these ideas brew in my head over several days. I thought about it while getting on with other things, going for a walk, brushing my teeth, whenever I could spare some brain processing power. The next few sections in this article are also part of the broader brewing stage.

Choosing the narrative • This is tricky. What story should I use? But the first question I ask myself is a different one: What's the story behind the Python issue I want to write about?

I find it useful to personify Python or the Python program and to link what's happening in Python to human traits, emotions, actions. Here's what this process looks like in this case—a reminder that a quick read of the Python article would be beneficial to understand my thought processes better:

Python didn't know how to group like objects together since these were objects the programmer had defined from scratch. So, Python interpreted the request as literally as possible and only looked for repetitions of the same object, not similar ones. But when the programmer clarified what Python should look for to determine whether objects are equal, Python had no issues returning the correct value.

Thinking of the program in human terms provides the first step towards creating a story. It provides the narrative for the story. Now, I needed an actual story to fit this narrative.

Choosing the story • More brewing is needed to get to a story. There's no magic trick to find the right story.

The first scenario that popped into my head was a weird one. But here it is: Two people standing in the street. One of them asks the other one to go around the block to count all the cars like that one while pointing at a car.

The other person goes round the block and then comes back, saying that's the only car like it. They're all a bit different in one way or another. But the first person then clarifies it's all the blue Ford cars he wanted him to count. Now that the task is clearer, the second person can count the number of cars that match those criteria.

But this didn't feel like the premise for a compelling story. Why would a person ask another one to count cars? Are they salespeople? Are they carrying out a survey? Are they thieves? I could have created a story from one of these ideas, but they didn't feel real enough.

So, I went back to the original premise–the basic one: A person asks another person to count something but doesn't give clear instructions on how to choose what to include in the group. Then, the issue is resolved with clear instructions.

I asked my family for ideas during dinner one day. I presented the premise above. We soon converged on food as the primary theme—probably because we were having dinner! We came up with the idea of a shop that sells food. So, I settled on a bakery or confectionery, and the food item that would take centre stage was a biscuit. I'll discuss one concern about this choice in the appendix below.

In the end, I chose to set the story in a patisserie just so I could use the alliteration The Python Patisserie (suggested by my son), even though patisseries don't usually sell biscuits.

Choosing the characters • Great! I now had the setting and the general idea of the story. Importantly, it was a story that fits with the key point of the article–a story that reflects the Python problem. Now, I had to fill in some details.

I needed characters. And even though I wasn't writing a novel, the characters still needed some, erm, character!

• First up was the moderately annoying and fussy customer, Mr Bakeman, who wanted a particular type of biscuit. Mr Bakeman doesn't really contribute much to the story, but giving him some personal traits helps the reader picture the scene.

• Then came the shop owner, Angie, and the new staff member, Todd. These come as a pair, as I'll explain below.

  • Todd, the new employee, didn't know much about biscuits. This point is important as it mirrors the idea that Python doesn't know the context when you ask it to count items it knows little about. In Python, you can create a class named Biscuit, but that won't mean anything to Python. That's the key difference between programming languages and humans. Todd's clueless nature fits this narrative well. But more on Todd later on.

  • Angie, the patisserie's owner, is the one in charge. She's the one who knows what's happening. If Todd represents the Python program, Angie is the programmer. At first, she just points to a biscuit and asks Todd, "How many of that do we have?" But Todd takes her literally and says there's only one of that biscuit. Angie then clarifies that she's referring to biscuits with the two key characteristics: they're shortbreads and round.

More on Todd and Angie later.

Writing the code • My articles are about Python programming. Therefore, they include computer code. As you can imagine, this is a central part of the technical content.

In this case, the code was easy to write and followed naturally from the story. However, in other articles I write, the code can be more involved. The code and the story need to fit well with each other. So, I often need to revise the code and the story a few times to make sure they complement each other.

In longer articles with longer code sections, I often write the code twice. The first time, I just construct the code until I have a functioning version. Then, I re-write it with a didactic mindset, writing it the way I feel I should teach it rather than the way I would naturally write the code. This step often serves as a planning stage for the main body of the article.

However, I skipped this step for The Python Patisserie article as it wasn't required.

Write the story. Write the article • The hard work was done at this stage. By now, I had the code I was going to use and a very clear idea of what I was going to write and in what order. Personally, I prefer to write the article from beginning to end, starting with the introduction and then proceeding with all the sections in the same order they'll appear in the article.

I planned to write this article as a full story-framing post. In full story-framing, the story runs through the whole article, or nearly. In other articles, the story-framing may give way to sections that focus exclusively on the technical content without the story.

The key points I wanted to demonstrate were clear by this stage (I'll write these as technical points, which make sense from a Python perspective but may not make much sense to non-Python programmers):

• .count() will use the object identity to group items if .__eq__() is missing.

• But it will use .__eq__() if it's available.

However, I also wanted to show an intermediate step–an example in which the same object is included more than once in a list to show that .count() still counts it multiple times even if .__eq__() is missing. I felt this was an important step in narrating the technical details, gradually building up to the final solution. But this raised a problem…

Swerving off course • This scenario doesn't make sense in my story. I used boxes with biscuits inside as the list of objects in my story. How can the same biscuit–the exact same biscuit–be in the box more than once? You could have a similar biscuit, but not the same one.

I didn't let this small inconvenience derail my entire story. So, I included a small section about an impossible box, one that somehow contains the same biscuit twice. It's a bit weird, a bit surreal, but this was a minor part of the article and I felt it's OK to put in this weird example.

However, if this was a major aspect of the topic, I would have to consider whether my story isn't appropriate after all. This is tricky. It's hard to scrap everything and start again from scratch when you discover a flaw in the story after you've invested time and effort crafting the narrative and possibly writing parts of the article. Luckily, this wasn't an issue in this case. But I have scrapped entire ideas in the past when I felt I was stretching the narrative too much, and the story may hinder rather than help.

Finishing off • The story-framing went through the whole article in this article. This isn't always the case. For more complex tutorials, I often limit the story-framing to the introduction and conclusion, with some anchors throughout the article.

Still, I wanted to dedicate the final sentences to the story rather than the technical detail. I often do this, but I had a further reason for this decision in this case.

In the article, I didn't explicitly state that Angie, the shop owner, represents the programmer and Todd, the employee who doesn't know much about biscuits, represents the Python program. I felt I didn't need to spell this out, and I could let the reader make this link.

However, in other articles, I may choose to make connections between the story and the technical content more explicit. This approach may blunt the literary sharpness of the story—it's always best to let the reader make such connections from a storytelling point of view. However, the primary aim of technical articles is to ensure the reader understands the technical topic. For this reason, I may choose to make any such connections clear to prioritise the didactic needs. The story takes a supporting role, unlike in a novel!

So, let's get to the final sentences in the article. Todd kept his job at the patisserie since when Angie learnt to communicate clearly with him, he was actually quite good at this job. Python will do what the programmer asks and wants if the programmer's code is clear and precise!

Appendix • Questions I thought about throughout the process • Here are some things I considered throughout the planning and writing process and the decisions I made:

• Should I use biscuits as the key food item in the article? The word "biscuit" is one of those many words that have different meanings in different variants of English. What British English calls biscuits are cookies in US English, and biscuits are some other food items in the US. In this case, I chose to stick with the British focus as I don't think any confusion on what I mean by biscuit will detract from the story or its message.

• And once I decided to keep using biscuits, I had to decide whether to write a note explaining the difference in terms and that I was referring to British biscuits in the article. Decision: I didn't add a note. I didn't feel it was necessary in this case. Notes and asides are great when they're needed, but they also distract from the main flow of the article. So, I only add them when I feel they're needed. I did make a compromise in the article—I linked the word shortbread to its Wikipedia page.

• Technical point: Should I add a note that .count() isn't just a list method but a method common to all sequences? This fact would be one that many readers may not know, and it links well with Python's duck typing philosophy. In fact, it's an interesting point, so surely… No, I chose to leave it out, too. Reasons: I had three options. I could just mention this fact in passing without further explanation. But readers can find this approach frustrating. Or, I could explain the fact in a bit more detail, perhaps using three or four sentences. But this would take the reader off course. Is it worth the detour? I decided it wasn't. So, I went for the third option: I didn't mention it at all.

• Technical point: Should I explain .__eq__() in a bit more detail? I chose not to. I'll assume my reader knows about this special method. This is a call I make on a case-by-case basis in my articles. Sometimes I choose to explain the tools I use even when they're not central to the article, but I can't explain everything all the time. In this case, my decision was made easier as I wrote about this topic only two weeks earlier. My readers will know about .__eq__() from that previous article and wouldn't want to read about it again.

• Technical point: When showing the example with a_string and another_string, which were both equal to "The Python Coding Stack", should I explain that this demo works with this particular string and in the manner I used it in my article, but may not work if the reader tries a different string or in a different environment? The issue here is rather technical and very much off-topic for the article. If the reader, say, uses a different string to the one I used in the article, a relatively short string without spaces or other punctuation marks (except the underscore), then CPython interns these strings, and the objects won't be different. Decision: I ignored this potential pitfall. It would be too much of a distraction from the main flow of the article. If a reader tries this with another string or in a different environment and it doesn't work, hopefully, they'll think of trying my code next! They can ask why theirs didn't work in the comments, and that will make for an interesting discussion. I also considered using lists instead of strings in this example. This pitfall disappears with lists. But I didn't want to confuse things since I needed to use a list to contain these two objects, the list I used to call .count(). So, it's best to use a different data type within the list. And using another mutable data type would add complexity unnecessarily.

  ---

  Get a copy of my latest book, Breaking the Rules. Available in paperback or ebook…

Get Your Copy Now

I don’t publish too often on this Substack, but you can stay up-to-date and make sure you get each post by subscribing below…

Subscribe now

I'll keep this brief as there's more detail on the webpage.

Breaking the Rules brings storytelling to technical writing. But it's not just about telling stories—that's only one of the narrative techniques. There are other methods we can borrow from great storytellers and adapt them to technical articles.

Let's bring more storytelling techniques to technical writing.

Let me know what you think…

Stephen

Get the Book

This article is about cognitive load—the amount of mental effort needed when learning something. Just like pushing a wheelbarrow full of bricks up a hill—which I'm sure you all do everyday—the lower the load, the easier the task. More on this soon.

But, getting back to the questions in the first line, there are three types of cognitive load. And the terms used are guaranteed to increase your cognitive load as you learn about cognitive load. Ready? There's intrinsic, extraneous, and germane cognitive load. I bet you use all three of those words several times a day, perhaps while shopping at the supermarket or cooking dinner.

And this is, in part, the point. When you write technical articles, you expect your reader's cognitive load to be high. But there are ways of lowering it. Narrative techniques do just that.

The three types of cognitive load • The most straightforward type of cognitive load is the intrinsic one. This is the load from the complexity of the content itself. Try to remember 2465 for 20 seconds. Easy, now try to remember 57292366293264656067264 for 20 seconds.

Some technical content is hard. Nothing much you can do about it. But not all is lost. Let's move on to the next category of cognitive load.

Extraneous cognitive load is the load created by the way the subject is taught. Many things I talk about in Breaking the Rules are designed to deal with this type of load. The content may be tricky, but you can deliver it in a way that's as clear as possible.

Germane cognitive load is the mental effort needed to create models. These mental models help your brain understand and retain the information. Analogies, for example, help to reduce this type of cognitive load.

Your mission, should you choose to accept it.. • Your mission is clear: reduce your reader's cognitive load. Why? Lower cognitive load leads to longer attention spans, which means your reader is less likely to give up. Longer attention spans also help your reader keep the stuff they read in the first part of the article in their short-term memory for when they read the later part. If your reader loses attention because of high cognitive load, they can't easily connect the material at the start of the article with that in the middle or at the end.

Lower cognitive load increases the chances the reader will understand. And lower cognitive load reduces the chances they'll misunderstand, which is different from not understanding—and more dangerous.

Shameless self-promotion • Cognitive load is a central theme in the book I'm publishing very soon, also called Breaking the Rules. It's a short book, deliberately so (I don't like when non-fiction authors pad out their ideas to make the book a "decent length"!)

It will be available in paperback and ebook.

And I'm also launching the Breaking the Rules community. As the name implies, it's a community of people who share an interest: technical writing. I'll support everyone in their quest to write technical articles and experiment with narrative techniques. But I really hope it's not just me helping you but all of us helping each other.

I'll share ideas in the community, and we'll surely have plenty of discussions around those thoughts. Members can share their article drafts, which we can review together and give each other feedback.

There's a one-time fee to become a part of the community, but this also includes the ebook and the video course (coming soon).

As I mentioned, I haven't published and launched yet—but it's imminent. You can preview the webpage, which has more details (webpage is a work-in-progress, so not all buttons work.)

I'll let you know when everything is live and published…

So here’s a sneak peek of the new Breaking the Rules webpage:

Breaking the Rules: Sneak Peek

And here’s a preview of the book’s cover:

Subscribe now

So why is history often communicated so boringly? Fact after fact after fact with dates and people's names and places and wars and treaties and…you get the idea. Stories are engaging. History is a story. Why isn't it narrated like one?

Well, sometimes it is. I just finished reading an exceptionally entertaining, immensely informative, enormously engaging story of the history of the Maltese language. Yes, I used both "story" and "history" in that last sentence. Deliberately. Even though it doesn't sound great. But hey, this is Breaking the Rules, so who cares?

If you're sufficiently fluent in Maltese, you can (and should) get a copy of Mela … l-istorja stramba, straordinarja (u sigrieta) tal-ilsien Malti kif ma jgħiduhilekx fil-klassi by Antoinette Borg (Merlin Publishers).

…and this article's title is inspired by the book's subtitle.

Yeah, I'm not writing about Python programming today • This Substack is about "narrative technical writing", but two of those three words can have broad definitions. I usually define "narrative" as the use of stories and storytelling techniques, but you can read the previous 17 articles for an, ahem, more detailed take on the topic.

As a scientist who now writes about programming, I usually define "technical" as science-y, maths-y, programming-y, if you know what I mean. But history and linguistics can also fit well into the technical domain. And they're also subjects that are traditionally conveyed in a rather—how can I put this politely—dour tone. Yes, bo-ring is what I really mean.

So, what can we learn from this storytelling masterpiece that we can use when writing about whatever "technical" subject we write about?

A story isn't just a sequence of events • The caricature of learning history paints the subject as a sequence of dates, each associated with a factual description of events. 1066: William the Conqueror lands in Hastings. That sort of thing.

However, what's more interesting is what happens in between those dates...and why it happens. This reminds me of the South Park storytelling framework, which I wrote about a few months ago: The South Park Technical Writing Manual (Ep. 14). There's a video you can find on the web where the programme's creators explain how they ensure that events are connected using "but" and "therefore" instead of "and".

The history of a language is full of "buts" and "therefores", and Mela's author takes the reader through this weaving journey. I knew many of the facts I read about in the book from my history lessons as a school child. But the "whys" were mainly missing. I knew about the pillars of the Maltese language–the counterparts of Shakespeare and Milton and Dickens–but their life stories, which I didn't know, put a whole new layer of context to their work.

A programming tutorial can easily be written as a sequence of facts. That's the easiest way to write a tutorial. But just like with the history of a language, or any history, it's what happens in between those facts that's key—and why it happens.

Language • How often do you read out aloud (excluding if you have young children)? Not often, I know. But if you did, would the language used in the book sound like the language you use with your mates when you're chatting in a coffee shop or down the pub?

Sure, there are instances when the language needs to be more formal. But can you justify writing a tutorial about [insert topic] in a formal tone—a tutorial whose only purpose is to inform and teach your reader about the topic? Which tone is likely to help your reader learn the material effectively? I know you know the answer!

The reader • Do you know who one of the main characters in the story of the Maltese language was? Yours truly! Or so it seemed as I read Mela. I was even entrusted to be the detective in a murder mystery involving one of the early pioneers of the Maltese language.

And this is something I want to do more of in my own writing: involve the reader explicitly and directly. Sure, modern style guides recommend using the second person singular you when writing tutorials rather than the first person plural we or, worse still, the passive voice. I also use you in my articles on The Python Coding Stack to show I'm talking to the reader. But is that enough? Just switching to using you, while definitely beneficial, may give the author the impression they've done enough to include the reader.

We can do more. Oops! I meant "You can do more". My journey through the history of Maltese encouraged me to actively participate in the book by prompting me to stop and think about an issue, answer questions, figure out which historical anecdotes may be true or false, and, yes, become a detective in a centuries-old murder mystery!

Conciseness • I promised to keep these musings brief, so I'll stop here, even though there's more I could write. And that's another thing we can learn from this book. History books, like programming tutorials, can sometimes go on and on, meandering through every (in)significant detail. But, as the cliché goes, sometimes (often), less is more.

Afterword • Breaking the Rules is breaking out of the confines of these words and sentences, bits and bytes here on Substack. There's already a Discord forum set up (1. It's brand new. 2. Yes, I don't like Discord, either. But it's the least bad of all the platforms to create forums/fora and communities. 3. Thanks for asking, here's the link to join.)

The technical article review club will start soon. It's like a book club, but for technical articles, and it focuses on technical writing rather than the articles' content.

And I'm starting to record video lessons for a course on narrative technical writing. I'll start releasing this course soon.

No, no, this won't be a course that will teach you how to set up a publication, make $$$ per month from your writing, or tell you all the useless/boring stuff you can figure out for yourself. This course, the Breaking the Rules course, will take you on a journey through storytelling, convincing you that humans need stories, they thrive on stories, and they learn best from stories. I'll present evidence from history (all of humanity) and science. We'll talk about cognitive load and how to reduce it, how the brain visualises what we read, and why all this matters when we write, and lots more. And, of course, I’ll discuss how to apply all of this to your technical writing.

So no, this will most certainly not be one of those follow-these-seven-steps-to-success self-help cr--ash courses (phew, I was about to write something else there.)

And this is not just theory. I practise what I preach, so you can have a look at my experiments with narrative technical writing at The Python Coding Stack.

Join the Breaking the Rules forum or stay tuned here to find out more (or send me an email to tell me you're interested.)

--End of promotional message. Sorry!--

Subscribe now

But it got me thinking, and now I know where the confusion arose.

Formal is not necessarily boring • If I describe an article as formal, would you automatically assume it's boring? I wouldn't. Communication can be formal and engaging. The opposite of formal is casual. The opposite of engaging is boring.

So, here's the two-dimensional spectrum where you can place all communicators. There's Boring-Engaging on one axis and Formal-Casual on the other.

And it's your lucky day, as I even spent a whole two minutes preparing this graphic for you in Canva:

Where do these people fit in the quadrant? • Never mind technical writing for now. Let's look at some famous figures from the past and present. Think of some of the great orators like Churchill or JFK. Most of the speeches you've heard them give are formal. But they're always engaging, definitely not boring.

Let's place them in the bottom right quadrant. They're both quite engaging but also fairly formal.

Next, let's look at another engaging communicator, Steve Jobs. And let's compare him with his successor at Apple, Tim Cook. I'd say Steve Jobs's natural style of communication is casual. Think of all those keynotes we keep seeing again and again. And he's engaging. But I don't think you can say the same about Tim Cook. I'd say formal and boring:

And since we're talking about CEOs of tech companies, here's a casual and boring one:

Sorry, Zuck! Don't be fooled by his long name straddling the purple casual/engaging quadrant. It's the dot hugging the left edge that matters!

Let me finish with one of my favourite communicators. This one is a technical communicator, and one of the best ones ever: Richard Feynman. He's very engaging, that's for sure. Whether he's casual or formal depends on which of his comms you consider. His lectures are on the formal side, but not too formal, and definitely high on the engagement score. Let's place his lectures on the chart:

By the way, I'm not being inconsistent. I used last names only (or initials) for historical figures and full names for contemporaries (I remember Steve Jobs well, so he's a contemporary in my book!)

Why is this useful? • I don't know. This is an idea I'm still working on in my head–and you're welcome to contribute in the comments. Maybe it's obvious to some of you. Maybe not.

My thoughts so far: You don't want to be on the left. Boring is not good. Some may say that academic papers, for example, can (and should) be boring, but I'm not sure. Textbooks definitely used to be formal and boring. Still, I think the best textbooks I read have been at least formal and engaging, some (like the one I wrote!) even verging on casual and engaging (I hope).

As for the top and bottom halves, I don't think there's a right or wrong (as long as you're in the right half). Some publications and communications need to be formal. And writing formal yet engaging articles and tutorials is not easy! But it's possible. When describing the publication I referred to at the start of this article, I should have said it's formal and engaging, so in the bottom right quadrant. Being close to Churchill and JFK is not bad!

And in the same way that formal doesn't necessarily mean boring, casual doesn't necessarily mean engaging. I see many technical authors who attempt to be casual, but their content is similar to old-style boring tutorials. Casual is not enough. If you want to be casual, you need to ensure you're also engaging.

Personally, I like to be in the top right quadrant. At least, that's what I aim for. It's up to my readers to decide…

Afterword • I'm running a two-hour live workshop on technical writing on Tuesday, 16 July. I'll discuss key topics relevant to all technical writing styles, but I'll focus significantly on using storytelling techniques to make technical writing more effective, more engaging, and, yes, more entertaining, too.

Humans love stories. Stories have been around since the start of humanity. We understand and retain information better when presented in a story we can relate to. I've condensed my years of research, experiments, and experience into this two-hour workshop, live on Zoom.

Join me if you can…

You'll probably look at the covers of the forward-facing books first and pick the ones you like. You may then read the blurb, which gives you a vague idea of what to expect from the story. But you already know it's like the advert telling you this frozen pizza tastes like the one you get straight out of a wood-fired oven in Naples. You may open the book and read the opening paragraph or two.

But you don't do any of this when picking a technical book or article to read. And a look at my bookshelves with technical books confirms this—the book covers are largely meh! (One programming book has a picture of a rat on the cover. What the…?) Except The Python Coding Book, of course, which looks great, and you ought to frame it and hang it over the fireplace.

Book and article titles • And the rules for choosing titles for technical books and articles differ from picking the name for your bestselling novel. Most people will only read the book or article if it's about a topic they want to learn. Normally, this means the title should make this clear.

This poses a problem for the more narrative style of technical articles. And as you know, this is my manifesto (how I dislike that word) for more storytelling and narration in technical writing. If the article has a strong element of storytelling, an old-fashioned technical title may jar.

Often, my solution is to use a two-part title. As an example, I picked a couple of articles from my other substack, The Python Coding Stack. One is called "The Curious Little Shop at The End of My Street • Python's f-strings" and another "The Strange Practices at The Broadcaster's Inn • Broadcasting in NumPy". Even if you're not au fait with Python, you'd have figured out that the first part of each title is the title of the story and the second part is the conventional mention of the technical topic.

Stealth Teaching • Apologies. I've taken a long-winded route to get to the main point of this post. I'm planning an experiment with one of my upcoming articles on The Python Coding Stack: Stealth teaching. Let me explain.

There's a rather advanced topic in Python that many beginner and intermediate learners find hard. I remember being put off learning this topic so many times in an earlier stage of my own learning journey. If I include the name in the title, I fear many will do the same and decide this topic is not for them—not yet.

But I think I can explain this topic well to the uninitiated—as you can see, I don't lack confidence when it comes to explaining complex concepts clearly! It's my job, after all.

I tried this method in a live lesson recently. I made sure I only mentioned the topic's name towards the end of my session. And the way I introduced elements of the lesson kept the real nature of the topic hidden until late in the session.

I'll follow the same path when I translate this lesson into a written article. And, of course, the title will have no reference to the topic either. Otherwise, what's the point?!

Drawbacks • The drawbacks are obvious, but I'll state them anyway. Anyone "just browsing" is unlikely to want to read the article. Anyone looking for this topic in particular won't find it. Yes, the topic will be mentioned several times towards the end, but you don't need to be an SEO guru to know that won't make a difference.

I'm relying on my regular readers, those who read my articles every week or almost every week. They may decide to read it based on their previous experience reading my articles—if they're still subscribed to my substack, I have to loosely assume they like the articles, at least a tiny bit.

But, for those who've been putting off learning this topic, which I'm not mentioning here, of course, the experience will be worth it—hopefully.

Afterword • Today's post is less coherent than usual. Sorry. But for those who've been following Breaking the Rules from the start, you know that I'm not writing this for you! These posts are my personal journal, where I record my reflections. So, I'm publishing this draft-like post anyway.

Speaking of which, you may see posts more frequently on Breaking the Rules in the coming weeks and months since I'm planning to…

…Nah, I'll tell you another time.

Subscribe now

It’s much easier to write a 3,000‐page introductory textbook than a 300‐page one. But I believe a 300‐page one is more useful.

Full disclosure: I'm quoting myself. I wrote this in the final thoughts of the Python programming textbook I just published. I'm telling you all this for two reasons:

1. It's an excuse to plug my new book.

2. Writing the book made me think about and appreciate more the point I want to share in this post.

A key skill for an educator is knowing what not to say, what to leave out when teaching. Or writing a technical article.

But surely, more is better, no? • No.

Let's start with a "proof" of this. I plan to teach my son how to prepare scrambled eggs. Here are two scenarios:

1. Here are three eggs. Scramble them.

2. Beating eggs denatures the proteins within them. Proteins are long chains of amino acids that unravel and elongate when denatured. This process exposes amino acids that repel water (hydrophobic) and attract water (hydrophilic). As the egg whites are beaten, these proteins uncurl and stretch out, forming structures that trap air bubbles, resulting in a lighter texture. The physical act of beating causes the protein strands to stretch and denature, allowing for the formation of a solid mass from a liquid solution of protein.
   

   When eggs are scrambled, the protein structure undergoes denaturation and coagulation due to the application of heat. The proteins in eggs, primarily ovalbumin, unfold and loosen from their folded structures when exposed to heat. As heat is applied, these proteins collide and form a 3D web, transitioning the egg into a semi-solid state. The denatured proteins expose their hydrophobic and hydrophilic ends, creating a network that traps air bubbles and water, resulting in the formation of scrambled eggs.
   

   It's important to note that egg whites and yolks coagulate at different temperatures, with egg whites starting to coagulate at around 60°C (140°F) and yolks requiring slightly warmer temperatures. By understanding this process, one can achieve the desired texture of scrambled eggs by controlling factors like the addition of liquids, cooking temperature, stirring technique, and timing to ensure a fluffy and creamy outcome.

Scenario 1 clearly provides too little information for someone who's starting from no knowledge of how to cook scrambled eggs.

Scenario 2 clearly provides too much information for the same person.

The ideal amount of information is somewhere in between these two.

Ergo, more is not better.

Scenario 2 generated by Perplexity AI. Life's too short for me to research this and write it myself. If your scrambled eggs are ruined, blame AI.

Cognitive load, working memory, and all that • Let's say we could categorise the stuff you need to understand about a certain topic into 10 stages. And you're a complete novice. You can't learn stages 1 to 10 simultaneously. That's fairly clear.

But there's also a delay between each stage. Each stage needs time "to brew", and the successive stage will only truly make sense when the previous one is well understood. These are those "Aha!" moments when a topic clicks in place.

Present too many stages to a beginner, and not only will the later stages be hard to understand, but they'll impact how efficiently the earlier stages are understood.

300-pages instead of 3,000 • Did I tell you already I published a textbook? Yes, I think I may have. I spent so much time and effort deciding what not to include–not because I didn't want to write more (in fact I already wrote most of the "extra" stuff I didn't include), but because I think the result is better for my intended audience.

Afterword • There's so much more I'd like to say about this topic. But I won't. Not yet.

Subscribe now

But one of the simplest is the South Park method. There's a video you'll find on the interweb where Trey Parker and Matt Stone, South Park's creators, explain their approach to a group of students at New York University.

Here's how it goes. List all the key events in your story. If the phrase connecting all the events is 'and then', you're f- finished, yes, that's the word they must have used!

Instead, connect the events either with 'and therefore' or 'but'.

Why? • Causality and Conflict • They go on to explain the motivation for this shift. A sequence of events doesn't make a story. The causality between events — the 'and therefore's — and the conflict between events — the 'but's — are the key ingredients that transform a sequence of events into a compelling story. And the conflict leads to a resolution, another key part to most story arcs.

Maintaining the Focus • Another benefit of this framework is that it helps maintain the focus. The sequence of 'and therefore's and 'but's helps the story stay focused and prevents the storyteller from meandering from the central narrative.

From Satirical Writing to Technical Writing • Technical writing is well-suited to the 'and then' approach. Every topic is always made up of a sequence of events or steps.

However, I argue that we should avoid this. The South Park method applies here, too. If we can connect the events through a narrative, the "story" linking the technical detail helps the reader engage, follow, and understand the topic. We can find causality. And we can even find conflict that we need to resolve.

I'll try to demonstrate the two approaches using an example from Python programming. I'll keep the explanations short—shorter than I usually would—since the purpose of this article is not to teach Python functions. Go to The Python Coding Stack for that!

Let me start by explaining function definitions using the 'and then' approach:

A function is a self-contained mini-program that can be reused when needed. This prevents you from repeating the same lines of code every time you need them to make the code less repetitive and easier to maintain.

You can define a function using the def keyword followed by a name of your choice. The function can have one or more parameters. These store information that's input to the function when you use it.

The function definition includes lines of code that are executed when the function is used. Any data created within the function is not available directly in the main program. You can use a 'return statement' to send information back to the main program.

I did not explicitly use the words 'and then' in this explanation, but I simply presented a sequence of accurate and descriptive facts. This is still the 'and then' style—we don't need to use the words directly, of course.

Now, let me present the same facts differently:

You often need to repeat the same lines of code in a program. You could repeat the lines of code every time you need them. However, this is repetitive and makes the code harder to maintain.

So, you can create a self-contained mini-program that you can reuse. This is a function, and it contains the lines of code that form the self-contained block. You can define a function using the def keyword, but you also need to choose a name for the function to use later. You may want to use the same code with different input information. So, you can create parameters to store these data when you define the function.

But since the function is a self-contained unit, any data you create within the function is not available outside of the function. This causes an issue when you need that information elsewhere in your program. But you can send information from the function back to the main program using a 'return statement'.

This section starts with a challenge that we need to resolve. The function is presented as a solution to this problem. Even the need to choose a name for the function is linked with a 'but'. The addition of parameters is also presented as a consequence of the need to use different inputs.

The self-contained nature of the function, presented as a feature of functions earlier in the section, now presents an issue. There's a conflict, but we can resolve this with the 'return statement'.

Note there are words like 'so' and 'however' to connect ideas and 'but' to show conflict. And even when these words are missing, the context linking sections implies causality or conflict (and its resolution.)

This made-up example, perhaps, is somewhat too artificial. I wanted to present a brief example of the concept I discuss in this post. But the principle applies to longer technical articles. You can change a sequence of facts into a more compelling narrative by linking the elements with 'and therefore's and 'but's instead of 'and then's.

Afterword • From late January, I hope to have more time to explore and write my thoughts about narrative technical writing. So, these posts will become a bit more regular than they've been in the past months. But I'm unlikely to try and stick to a rigid timetable as I did in the early days of Breaking the Rules. I'll post whenever I have something to post.

Subscribe now

For those of you who only read my Breaking the Rules musings, you may have assumed I've been abducted by aliens or my pinky was hurting. Those who follow my other Python-related content will have been reassured that I've not been assimilated by the Borg. In fact, you may know why these posts have been missing—there's been a lot more of all the other stuff!

I've been busy. And it's not just writing articles on my other Substack, The Python Coding Stack, which have been as regular as ever, but I've been releasing video courses for my new Python community that's launching soon (and some other videos for another venture that I'll unleash soon.)

And yes, fighting off those aliens trying to abduct me takes up time, too.

But don't worry. I haven't forgotten about my diary to document my technical writing ideas—this substack. But for now at least, posts won't be as regular as I originally intended.

Resistance is futile.

Live long and prosper.

Qapla.

But not today.

Today's post is about the author.

It's a short post since we don't want to steal the limelight away from our readers too much!

The selfish reason • I enjoy writing technical articles, as do most technical authors I know. Enjoying the writing process doesn't guarantee high-quality articles, but it helps.

The main reason why I've been experimenting with my technical writing is because I genuinely believe that introducing narrative techniques helps a reader get more out of the article.

But there's a secondary reason. A more selfish reason. This writing style makes the writing process more enjoyable for me. And this matters. Here's why.

Motivation • What keeps an author motivated to write technical articles? I promised a short post today, so I won't try to answer this question. But the more enjoyable the writing process, the more motivated the author.

I'm not a full-time writer. I write my Python articles (and my Breaking the Rules posts) in between my other daily activities. But since I enjoy writing, I make sure I can find time to plan and write articles and come up with different ideas on what to write and how to write. Indeed, I often write when I need to relax.

Mindset • A recurring theme in Breaking the Rules is the reader's mindset. I've written in the past, and will write again in the future, about how narrative techniques can modify a reader's mindset, priming him or her into a state that's more receptive to acquiring and retaining knowledge.

But an author is also human and, therefore, subject to the same psychological effects as the reader. Innovation, creativity, storytelling—these all help the author get into a better mindset. And this leads to better writing and better articles.

Afterword • And as today's theme is "selfishness", a quick reminder that I'm writing these posts primarily for an audience of one—myself. But I'm glad others may find some of my thoughts interesting to read.

Subscribe now

But I digress.

One of the candidates gave an example during the teaching demonstration that made me quickly reach for my notepad and scribble a reminder. This anecdote was perfect for an idea I was planning to write in Breaking the Rules. So, here we are!

It's the story of a single letter the candidate wrote on the screen.

In this post, I'll use coding examples. But don't run away… Don't worry if you're not familiar with coding. I'll explain what needs to be explained, and the key point in this post also applies to other types of technical writing.

A single letter • The candidate we were interviewing was required to introduce the for loop to the pretend class. A loop is a fundamental tool in coding that allows the computer program to repeat a number of lines of code several times. The candidate wrote this code on their screen:

 bookshelf = [
    "1984 by George Orwell",
    "To Kill a Mockingbird by Harper Lee",
    "Pride and Prejudice by Jane Austen",
 ]
 ​
 for books in bookshelf:
     print(books)

The first section creates a list of books labelled bookshelf. It contains three books. The last two lines loop through this list and print out the name and author of the books, one at a time. The line that prints the book is repeated three times, once for each book.

It's not the most exciting computer program ever, but it'll do to demonstrate the for loop. The for loop statement—the line that starts with for—also introduces a new variable. This is a label used to refer to each of the books. The candidate used the variable name books for this.

Let's start with positive feedback. The candidate chose to frame this example within the context of a simple story—the books are on a bookshelf. This is better than a context-free example, such as :

 nums = [1, 2, 3, 4, 5]
 ​
 for n in nums:
     print(n)

This type of soulless example is fairly common in coding tutorials. Not in mine, though! I wrote about framing technical content within a story in earlier posts in Breaking the Rules. [Frame It (Ep.3) and Frame It • Part 2 (Ep. 9)]

So, what's the issue with the code the candidate wrote?

It's the letter "s" at the end of books. It should have been book. This won't affect the code. The program will still give the same output. But it will affect the learning process.

Here's why. The key concept we want a learner to grasp when learning the for loop is that you have something which contains several items, such as the bookshelf with several books, and you go through each one of those items one at a time and repeat the same action on each book.

The variable name we choose should describe this process. The code the interviewee wrote, which used books (plural) as the variable name, can be misleading. We want learners to understand that this name is equal to the first book the first time the loop runs, then the same label is used for the second book, and finally for the third one.

The correct label to convey this is the singular book, not the plural books. It's just one letter. It may seem an inconsequential detail, but not for a learner trying to visualise what's happening.

A blank line • Here is code I often use when teaching the for loop to children. This uses a module in Python that allows us to draw simple (and not-so-simple) shapes on the screen:

 import turtle
 ​
 fred = turtle.Turtle()
 ​
 for side in range(4):
     fred.forward(100)
     fred.left(90)

We're fetching the module, which is bizarrely called turtle, and we create "a turtle" which will move across the screen to draw lines. We call him fred (deliberately using a lowercase "f", in case you're thinking I forgot my English grammar.)

You'll spot another for loop. This is a bit different from the earlier one. It repeats the last two lines four times to create a square. The sides of the square are 100 pixels long.

Anyway, I then add the following line:

 import turtle
 ​
 fred = turtle.Turtle()
 ​
 for side in range(4):
     fred.forward(100)
     fred.left(90)
     
 fred.dot(10)

This draws a single dot of radius 10 pixels on the last corner of the square. It only draws one dot because the line of code that draws a dot doesn't have an indent, and this is what Python needs to determine what is repeated and what isn't.

But some students used to think there's only one dot because of the blank line I left between the for loop and the line of code that draws the dot.

The blank line is there purely for display purposes. Blank lines in code are a bit like starting new paragraphs when writing. There's no fixed rule on when to use them. It depends on how you want to structure your code.

But beginners often think those blank lines affect the code. They don't

So, now I write this example without the blank line:

 import turtle
 ​
 fred = turtle.Turtle()
 ​
 for side in range(4):
     fred.forward(100)
     fred.left(90)
 fred.dot(10)

For the beginner, it should be clearer that the only difference between the lines that are repeated four times and the one that only runs once is the indent, not the blank line.

A small, almost insignificant change—but one that can make a significant difference to a learner.

It's a small detail but a consequential one.

Afterword • As you may know, I experiment quite a bit with my technical writing in my other substack, The Python Coding Stack. Recently, I went a step further and wrote, if that's the right word, a picture story about a Python technical topic. Even if you're not into coding, you may enjoy parts of this picture story: Clearing The Deque—Tidying My Daughter's Soft Toys • A Python Picture Story.

Subscribe now

In the early '60s, Caltech decided to modernise its undergraduate introductory physics course to make it more exciting and relevant. They approached Feynman, who was at the peak of his fame at the time. To their surprise, he agreed to deliver this undergraduate lecture series. But he had one condition: he would only deliver the course once.

The lectures' intended audience was the undergrad cohort, but the lecture hall often included graduate students and faculty members. And luckily for us, members of later generations, Caltech recorded the lectures. Therefore, the audience of the lecture series keeps expanding.

Confession • Why am I listening to these lectures?

Let me start with some context. I'm a physicist by training. So, I studied all the physics fundamentals in my undergraduate modules in physics. Admittedly, this was a long time ago, and I don't claim to remember everything from my undergraduate or postgraduate studies. Who does?

But here's my confession. Feynman's lectures are also available in book form. I bought the three-volume set over twenty years ago. I never read them.

So why now? I'm listening to these lectures as part of my quest to improve my technical writing—indeed, to improve my technical communication in general, including aural presentations. I'm glad I'm listening to Feynman's recordings rather than reading them since these lectures were delivered aurally—it's how they were intended!

But, but, I know this stuff already • So, I'm listening to these lectures as an exercise in technical communication, learning from one of the masters. After all, I know all the physics already, right?

But as I listen to these lectures, I'm also learning a lot about the physics. I'm not really learning new theories or laws of physics that I didn't already know. But I'm being exposed to different perspectives, different ways of looking at these physics concepts.

In the first lecture, Feynman talks about atoms in solids, liquids, and gases—this is one of the most basic topics in physics. But the beautiful picture that Feynman paints of the atoms jiggling and bumping into each other helped me understand freezing, boiling, evaporation, and other "basic" topics my daughter in primary school is currently learning! I thought I understood these topics fully before listening to this lecture.

The unexpected reader • You write your articles for an "ideal reader". But that doesn't mean your ideal reader is the only one reading. You may have an unexpected reader, too.

But today's post is not focused on you as a writer. It's about you as a reader. How often do you read articles about topics you already know in your field of expertise? How often are you the unexpected reader of someone else's article?

I often read articles about Python topics I already know well. However, I'm very selective about which types of articles I read. I gain the most from the ones that give the author's vision of the topic, not the ones that focus just on the facts.

And when I write my technical articles, I try to create a picture of the way I see the topic. I wrote about this a few episodes ago: A Near-Perfect Picture (Ep. 7). I've been honest about the primary motivations for this previously: I write these articles this way because it helps me clarify the topic in my own head. But hopefully, it also broadens the pool of readers to include more expert programmers who will still find the article insightful.

Afterword • You can listen to Feynman's famous lecture series here: The Feynman Lectures Recordings. Or if you prefer to read them, either buy the three-volume set or read them here: The Feynman Lectures on Physics: Volume I, Volume II, and Volume III.

I was listening to one of the lectures on my headphones while on my morning walk today. At one point, I couldn't refrain from laughing out loud at one of Feynman's jokes. Passers-by glanced at me, as often happens in these situations. I doubt they would have guessed I was listening to a quantum mechanics lecture from the 1960s!

Subscribe now

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!

Subscribe now

For the avoidance of doubt, I like breaking the technical writing rules. Not just any rules. I don't break the rules when playing Monopoly, say. Or when parking my car!

So why break the rules? • For this week's post, I got a second opinion on why and when to break the technical writing rules. I asked a "colleague" to provide this perspective.

Here's the question I asked the "colleague":

What is the justification for breaking the technical writing rules?

And here's the response my "colleague" gave:

Unedited output from my "colleague", also known as GPT-4. The prompt used is the question shown above.

Technical writing generally follows a strict set of guidelines and rules to ensure clarity, accuracy, and ease of comprehension. These rules serve critical functions: they establish a baseline of quality, improve accessibility, and allow for the effective transmission of complex ideas. However, there are scenarios where breaking the rules might be justified:

1. Audience Adaptation: If your audience is more receptive to a casual or unconventional style, then deviating from strict technical writing norms could enhance understanding.

2. Innovation: Creative ways to present information can make it more memorable or impactful. In these cases, the objective of clarity justifies rule-breaking.

3. Engagement: In some contexts, strict adherence to technical writing rules can make the material dull and less engaging. Varying sentence structures or using rhetorical devices could make the content more engaging, which might ultimately facilitate better understanding.

4. Clarity over Convention: If a rule actually impairs understanding rather than aiding it, then breaking it would be beneficial. This is particularly true when technical jargon or formalisms make a document harder to understand for its intended audience.

5. Niche Requirements: Specialized fields may develop their own set of best practices, which might diverge from traditional technical writing rules. In such cases, following the field-specific guidelines could be more appropriate.

6. Limited Scope or Time: In some settings, you may not have the luxury of space or time to adhere to all technical writing best practices. An executive summary, for instance, might have to break some rules in the interest of brevity.

7. Establishing Authority or Brand: Sometimes, deviating from the norms can help establish a unique voice or brand. However, this must be done carefully, and the potential costs in terms of clarity and accessibility should be weighed.

8. Human Touch: Rules can sometimes strip away the humanity in writing. Adding personal anecdotes, humour, or other elements that are typically avoided in technical writing can make the material more relatable, provided it doesn’t compromise the integrity or clarity of the information.

9. Updating Outdated Norms: As our understanding of effective communication evolves, some traditional "rules" might become outdated. Breaking them could align the document with contemporary understanding.

10. Legal or Regulatory Exceptions: In certain circumstances, legal or regulatory requirements might necessitate breaking traditional rules, such as when certain types of disclaimers or language are required.

11. Cross-cultural Communication: In international contexts, rules may need to be adapted for better comprehension by audiences with different linguistic or cultural backgrounds.

Breaking rules in technical writing should not be done lightly. It is crucial to weigh the benefits against the potential costs, like confusion, misinterpretation, or loss of credibility. If you do break a rule, make sure to provide cues that help the reader navigate the text, and be prepared to justify your choices.

Not bad, dear GPT! Not bad.

The human is back • It's my turn to comment on GPT's views.

1. Audience Adaptation: This topic is on my list to write about soon. I haven't yet. Are you writing technical articles for your personal audience, readers who know you and trust you? Or are you writing for a general audience, perhaps in a publication with other authors?
   
   The more personal your audience is, the more you can—and should?—break the rules.
   
   Let's take the introduction of an article. The classical introduction of a technical article is to introduce a topic, to show why the reader should be interested in this topic and why it's important, and to convince the reader they should read your article and not someone else's.
   
   But if your audience trusts you, you can replace this introduction with something else. Perhaps something to improve engagement, understanding, and retention of the material your audience reads. I wrote about this in my two posts on story-framing, part 1 and part 2.
   

2. Innovation: Let's be honest. Classical technical articles are boring. I know it. You know it. A keen learner will live with this since they want to learn the topic. They're self-motivated. But, as GPT put it, "creative ways to present information can make it more memorable or impactful". This can only be a good thing, right?
   

3. Engagement: GPT did a good job at outlining why and when breaking the rules of technical writing is justified. But there's quite a bit of overlap between the points 2 and 3. This human would have merged these points into one!
   

   GPT mentions "varying sentence structures" in its comment about engagement. I wrote about this topic a couple of weeks ago in The Rhythm of Your Words (Ep. 8). No bribes were paid to GPT to include this point, I promise!
   

4. Clarity over Convention: I have to admit I had to re-read this entry several times to figure out GPT's key point. But if I understand it correctly, I agree! The main point of a technical article is to help the reader understand a technical topic. Therefore, clarity of communication should always come first.
   

   GPT makes another important point. Technical jargon makes the article harder to understand. We need to use technical terms, but we can do so carefully, ensuring terms are introduced at the right time. I often prefer to explain the problem and concept first, before introducing the terminology. By using this technique, the reader already understands the concept before being introduced to a complex-sounding name for it.
   

5. Niche Requirements*
   

6. Limited Scope or Time*

   *I'll skip these. Not sure I have anything meaningful to add.
   

7. Establishing Authority or Brand: GPT went into marketing-mode for this one. If you're writing the same articles as everyone else, you'll go unnoticed! But does this make the article better? Probably not. But more people may read them. And that's also important!
   

8. Human Touch: Traditional technical writing leans towards impersonal articles that focus exclusively on the content. And the content is what matters most in a technical article. But you can still write about the content–and do so thoroughly–while having a more "human" conversation with your audience.
   

   One of my guidelines when writing an article is to imagine that I'm sitting in a comfortable, quiet coffee shop with my ideal reader, and we're discussing the topic while sipping a cup of coffee. That's the tone I aim for when I write a technical post or tutorial.
   

   And in this new era of AI-generated content, the human connection between writer and reader will likely become more important.

   I'm sure you didn't miss the irony of GPT suggesting this point to us!
   

9. Updating Outdated Norms: You've heard this conversation before:
   

   Q. "Why do you do things this way?"

   A. "Because we've always done it this way!"

   
   GPT phrases it this way: "As our understanding of effective communication evolves, some traditional 'rules' might become outdated". One of the future themes I'll write about on Breaking the Rules will be the research into effective communication, storytelling, neuroscience, psychology, and other topics that can and should influence our best practices. "This is the way" works well for Mandalorians (for those of you who are Star Wars fans). But it's not how science works. If the facts change, so should our opinions and practices. Revolutionary thought, I know!
   

10. Legal or Regulatory Exceptions: OK. Let's move on.
    

11. Cross-cultural Communication: Here's the geographical distribution of my subscribers on The Python Coding Stack:

    

    The truth is you can't write for everyone. Expectations and styles vary in different parts of the world. But in today's international arena, are these differences becoming less relevant? We'll see.

As you can see from my comments on all the points GPT made, I'm not necessarily enamoured by all of them. I'll be completely honest with you, I had never considered "legal and regulatory exceptions" as a reason to innovate and experiment with my technical writing! I still don't.

But I do believe that technical writing is evolving. Everything changes. But not everything changes at the same pace.

I'll keep experimenting with ways to make my technical articles more enjoyable, more engaging, more memorable, more effective, and more personal. And, of course, I'll keep writing about this experimentation here on Breaking the Rules.

Afterword • Today's post zoomed out to look at narrative technical writing as a whole. I'll do this from time to time as it's too easy to get too focussed on specific techniques without seeing the bigger picture and making sure it all still makes sense.

Next week, I may follow up on this post with a review of the ten articles (plus one pilot episode) I published so far on Breaking the Rules. So if you missed anything while on holiday, fear not…

Subscribe now

In Episode 3, I discussed how to frame the technical content within a story. Start the article with a narrative paragraph or two, then pivot to the technical content using examples that fit the story you used to frame the article.

Setting the scene • I recently used this technique on a series of articles about object-oriented programming, which is not the simplest topic in programming. The framing story is based on Harry Potter.

In this branch of programming, we create classes, which are like blueprints to create many objects of a similar type. The examples in the articles are all on-theme, creating classes like Wizard, Spell, House, and Wand.

Why? • So we know what story-framing is. But why go through all the trouble? What are the benefits? And what about the drawbacks?

Let's start with the drawbacks. If you start the article with the introduction to a story, you cannot introduce the technical topic. The traditional technical article introduction explains why the topic is important and tells the reader what to expect.

If someone is searching for an article on a specific topic, the traditional introduction can tell them if this is the article they're looking for.

Engagement • The story-framing approach takes a different route. Stories activate different parts of a reader's brain. Starting the article with a story puts the reader in a different mindset—literally. This can increase the chances the reader engages with the article. And an engaged reader is likely to get a lot more out of the article.

Attention • The cognitive load when reading a technical article is high. Reducing this cognitive load is a topic I'll return to often in Breaking the Rules.

One of the effects of high cognitive load is to reduce attention spans. We can't escape the technical detail in a technical article! But story-framing can help reduce the load, allowing the reader to stay focused for longer.

Retention • Better engagement and longer attention spans are good things, sure. But a technical article reader must also remember the concepts they read and learn.

The links between the technical detail and a memorable story help the reader remember the material longer.

When? • Is this technique suitable for every article? Probably not. The trade-off I discussed earlier is to replace the traditional introductory paragraphs with the story. You must be willing to give up the introduction to the technical topic in the first few paragraphs. I feel more comfortable using story-framing when my ideal audience already knows the topic I'm writing about in the article, and the aim is to dive deeper into the subject rather than introduce it.

Afterword • Breaking the Rules is two months old, and today's post is Episode 9. There was also a pilot episode, so it's really ten posts already.

I've just gone back to re-read the pilot episode. In that first post, I wrote: "You are not my intended audience. Sorry. I'm writing Breaking the Rules for an audience of one—me." Writing these posts has helped me process my ideas and clarify my thoughts. That's a good enough reason to keep writing. And if you also find them useful, so much the better.

Subscribe now

In traditional technical articles, the focus is on presenting the details of the topic coherently, systematically building layers on top of each other. The effectiveness of the article is closely linked to how well the author can structure the technical detail. However, this single-minded focus on the topic can lead the author to forget about the method of conveying that information.

Pace and rhythm • Think of your favourite speaker. Perhaps a comedian or a colleague who always gives engaging talks. Or a brilliant orator from recent history—recent enough that you've heard them speak live or through audio recordings—Churchill, JFK, Martin Luther King Jr. One of the best orators I know is the headmaster at my son's school. But you're unlikely to know him, so I can't use him as an example.

These speakers control the pace and rhythm of their speech perfectly. They're in charge. They slow down. They speed up. They pause. They adapt the tone of their voice. Their words matter, but how they say them matters just as much.

You can still use similar techniques when writing. You have less control than when speaking, but you're still the one in charge. You can change your sentence lengths, use punctuation marks to punctuate the flow of the article. Even the words you choose matter—a reader will slow down when there are many longer words.

Back to the start • Go back to the first section of this post and reread the first two paragraphs. Bonus points if you can read them out aloud…

I wrote the first paragraph using a mixture of sentence lengths—some are short and some a bit longer. None are too long. There are many full stops. And the comma before "hopefully" gets you to pause, hopefully! (Readers, don't ignore punctuation!). The first sentence is short. The next two get progressively longer. A medium-length sentence follows these.

The second paragraph has longer sentences. If you try to read this paragraph out loud, you'll likely read it a bit slower than the first one. It also includes longer words.

Why? • When you read fiction and other narrative pieces, you experience this control of pace, knowingly or unknowingly. In fiction, the author controls the reader's mood so that it matches the mood of the story. Is this still relevant for technical articles? Perhaps, the emotional mood of the reader is less important when explaining Python or physics.

But there are other reasons for controlling the pace and rhythm of your article. The change in pace keeps the reader more engaged and less likely to get bored and lose concentration. It makes your reader's experience more enjoyable, and they're more likely to understand the content.

You can also highlight important points in your article by moderating your reader's speed. This is a more subtle form of emphasis than using italics or bold.

And your audience can get to know you as an author better. They can "hear" you and your voice as they read the article. Traditional technical articles strip this personal information from the text. And a reader who can connect with the writer is more likely to engage and understand.

Afterword • When I write a technical article, I imagine sitting in a cosy, quiet coffee shop with my ideal reader and casually chatting about the topic. I try to mirror that feeling in my writing.

I'm experimenting more with pace and rhythm in my technical articles. And I plan to read more about the topic, too. There are other techniques used often in narrative writing that we can adapt to technical articles. Expect to read more about this from time to time.

Subscribe now

You can see the crispness in the air and the water spray rising towards the onlookers on the bridge. You can almost feel the calmness of this place.

Just a second… Some of you are telling me you can't see the image properly? It's a poor-quality image, you're saying? That's a shame! It means you can't see the beauty I was experiencing. I wish I could share it with you properly.

Sampling our thoughts • A good technical article starts with a clear idea of the topic in the author's head. That in itself is not a trivial step, but one I'll talk about another day.

The next challenge is to represent that idea in words. The written article is a representation of the author's ideas, but it's at a "lower resolution" than the raw thoughts that reside in the author's head. If that resolution is too low, we end up in a similar situation to the low-resolution image I shared with you earlier. You couldn't quite see what I saw when I looked at the bridge straddling the waterfall.

Our job as technical writers is to convert our ideas into writing using the highest resolution possible. Let's call this the conceptual resolution to carry on the analogy with spatial resolution from the imaging domain—apologies for getting a bit technical here.

If you can sample your ideas with a high conceptual resolution, your readers can form a picture close enough to the one you have in your head. But if the conceptual resolution is low, the audience will get a blurry vision of what you're thinking and what you want to convey to them.

From optics to writing • In a previous life, I worked as a scientist in the optics domain. I dealt with optical resolution daily. This is why I'm using the optical resolution analogy in this post. I'm probably breaking one of my own analogy rules (see Whizzing Through Wormholes (Ep. 2)) by using an example from a technical field—optics—to explain another concept. An analogy ought to "describe an everyday scenario that everybody understands" is what I wrote a few weeks ago.

Since I've already broken my own rule, I'll go further still…

Conceptual diffraction limit • In optical imaging systems, there's a fundamental limit to the resolution of an image called the diffraction limit. Even a "perfect" optical imaging system is not really perfect, and the resolution has an upper limit depending on several properties of the imaging system. A diffraction-limited optical system is the best you can hope for in any scenario.

The written article will never be a perfect representation of the thoughts in our heads. No matter how masterfully it is used, language will probably always stop short of conveying the full clarity of our thoughts.

Instead, when we write a technical article, we should aim for the conceptual diffraction limit—the best-possible representation in words of the ideas we have in our head.

That's easy enough to say. But so many key ingredients are required for anyone's writing to approach this theoretical limit. Breaking the Rules is about exploring as many of these ingredients as possible.

As mentioned earlier, the raw idea we have in our head must also be clear and coherent in the first place. Otherwise, not even conceptual diffraction-limited writing will convey much. It's like getting a professional photographer, using a high-quality camera, to take a photo of a blank, white wall. The photo won't convey much, even though the resolution is high!

Conceptual sampling theorem • I've probably lost most of my audience by this stage of this post. If you're still here (well done), let's go deeper and look at another result from my former profession. The sampling theorem roughly states that a minimum sampling resolution is required to reconstruct the original signal. We could extend a conceptual version of this theorem to state that there's a minimum conceptual resolution needed in an author's writing for an ideal reader to recreate the ideas the author is attempting to convey.

I should probably scrap that paragraph and re-write it. But I won't.

Afterword • I was struggling to write this post for weeks. And the result is probably a post that's not as clear as I would have hoped. I haven't fully managed, I feel, to paint a clear picture of the mental image I have of this concept. I don't need to point out the irony of this, of course…

I'll write again about this in the future.

Subscribe now

I took the kids to the museum the other day. There was an exhibition called "Python Programming Through The Centuries", showing the tools and methods used to program in Python from prehistoric times until the modern day.

In one of the rooms, there was a display cabinet with items the Sumerians used (c. 4000 BC) as debugging tools when coding in Python—the precursors of the debugging rubber duck.

Next to this display there was a vending machine stocked with crisps and drinks. This was odd. Thinking about it, lots of things were a bit odd about this museum.

We could look into the display cabinet. But with the vending machine, we could insert some money, tap a few keys, and get one of the items out.

Let's explore the Python special method __getitem__(), which will help us understand the difference between the display unit with the Sumerian debugging tools and the vending machine with the snacks.

This was the introduction I wrote for a Python article I published a while ago. I know some of you who read Breaking the Rules also read The Python Coding Stack. If you can't remember reading this introduction, don't blame your memory. I never published these paragraphs. Until today.

I used a different story to frame the article about __getitem__() because the more I thought about this analogy of the museum cabinet and the vending machine, the more it fell apart.

Not all analogies are good analogies • Here's the story of how this analogy went wrong. There are some analogies I've worked on for years. But this wasn't one of them.

I decided to write an article about a Python command called __getitem__(). If you're not familiar with Python programming, all you need to know is that it allows you to fetch an item from something with many items within in. For example, let's assume you have a shopping list called items_to_buy in a program. You can use square brackets, such as items_to_buy[2], to fetch an item from the shopping list, but only if this weird-looking command, __getitem__(), exists.

So I brainstormed, came up with a few ideas, and settled on this analogy. I wanted a slightly surreal scenario that shows two things that contain items. You could fetch items from one but not the other. The article would have gone on to deal with a "museum display" that doesn't have this __getitem__() command and a "vending machine" that does.

Great job, you're thinking. And I had started writing the code for this article, too.

But here's the problem.

Let's return to the shopping list example. If you run items_to_buy[2] in your program, you'll see what item is in that position, but the item will not be removed from the shopping list. So, you can see the item but not remove it from the shopping list. You'll need something else for that.

And that's where the analogy failed. I intended to show that the vending machine meets this requirement, but the display cabinet doesn't. But when you "fetch an item" from the vending machine, you remove it from the machine (unless it gets stuck!). This is not what happens with __getitem__(). And you can still "look" at an item in the display cabinet if you wish, which is what __getitem__() does, sort of. The real-life scenarios didn't match the programming requirements closely enough.

Going off-piste • I discussed the key ingredients of a good analogy in Episode 2: Whizzing Through Wormholes. The analogy needs to describe items or events that most people are familiar with, and there must be a good correspondence between the items in the analogy and the technical concepts they represent.

This analogy does OK with the first criterion but not with the second. The purpose of an analogy is to use an everyday item or event to clarify how the technical concept works. But the wrong analogy can lead the reader down the wrong path and misunderstand the concept. Having a wrong understanding of a concept is worse than not understanding it in the first place.

The fudge • Since this substack is about stories, let me finish the story about this article. I had invested time and energy in developing this analogy. But then I decided to ditch it for the reasons I outlined above. It's tough having to throw away an idea.

But I made another mistake. I tried to hang on to parts of the idea. The new story I used to frame this article about __getitem__() still had a vending machine. This time it was placed in a classical library in an old manor house. It was better, but still not perfect. I give myself a 5 out of 10—must try harder.

Afterword • I suppose all writers hope their writing improves over time. This doesn't mean the improvement is linear. Not every article will be a bit better than the previous one. Not necessarily.

I'm thinking about regularly re-reading my own articles with a six-month delay. I'll let you know what comes out of that exercise.

Subscribe now