Broken Rules (Ep. 10)
Let's not lose sight of why it's good to break the rules—sometimes
I love rules. And I love breaking them. This week, I took a step back from exploring specific topics in narrative technical writing to look at the big picture again.
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:
Audience Adaptation: If your audience is more receptive to a casual or unconventional style, then deviating from strict technical writing norms could enhance understanding.
Innovation: Creative ways to present information can make it more memorable or impactful. In these cases, the objective of clarity justifies rule-breaking.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.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?
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!
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.
Niche Requirements*
Limited Scope or Time*
*I'll skip these. Not sure I have anything meaningful to add.
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!
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!
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!Legal or Regulatory Exceptions: OK. Let's move on.
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…
Oh yeah, I'm pretty confident I break all of these. Agree completely that the clarity of message is the only thing that really matters, and sometimes you need to use something unexpected (EG, personal voice, off-color humor, or even something startling) to keep a reader's interest. We are fickle readers, we humans.