This blog post is about how to explain things in writing.

You should learn to explain things in writing because it’s the most efficient way of conveying an idea to a large, distributed audience. Whether digital or printed, plain text is portable and takes little space on a drawer or hard drive. Plain text is also easy to share and index.

Furthermore, good writing leads to good thinking, especially if you’re writing to explain something. Explaining forces you to find logical connections between subjects and reduce complex pieces of knowledge to concrete examples and actionable advice.

To teach you how to explain through writing, first, I’ll cover the basic structure of an explanatory text. Then, I’ll use examples to demonstrate why it’s helpful to go from concrete stories to abstract facts. Finally, I’ll give you a few tips regarding format, grammar, voice, and style.

With this post, I expect to show you that explanatory writing can be entertaining and allow authors to explore novel formats. Beware: this blog post is highly meta.

The basic structure of an explanatory text

Most explanatory texts adhere to the following three-step structure:

1. Explaining what they’ll explain and how they’ll explain it
2. Explaining it
3. Summarising what they’ve just explained

Imagine, for example, that you’re trying to write a blog post to explain how to wash clothes. In that case, your post should start by delimiting what is it that you’ll write about. Do not waste time talking about the history of washing machines nor the chemistry of fabric softeners. People are not interested (yet). Simply tell people you’re going to teach them how to wash their clothes.

Once you’ve told people that you’re writing about washing clothes, tell them how much better they’ll look using clean clothes. Perhaps spend a paragraph or two talking about the ways in which clean clothes make people smile more often and get more dates.

Sometimes, it might be worth switching the order of these first two steps. If you’re going to explain something as dull as washing clothes, it may be hard to get people to read it without embellishing the subject first.

In other words, you need to make your readers want to read. And, to learn with your text, readers need to know what you’ll write about.

Once your readers are “hooked”, tell them how you’ll teach them to wash clothes. Make it clear that you’ll talk about separating clothes first and about their washing machine’s settings second.

Finally, you’ll explain in detail how readers should wash their clothes. This is the ideal moment to explain the thousands of options in their washing machine’s dial and when to use each (or not to).

As you’re explaining the subject matter in detail, make sure not to deviate from the promise with which you’ve begun the text. If you want to talk about the manufacturing of washing machines or discuss which is the most environmentally friendly detergent, you should do that in a separate blog post. Remember: you’re teaching people how to wash clothes, no more, no less.

Finally, once you’ve taught people everything they need to know to have clean clothes, summarise the most important parts of your text, as I’ll do in the next paragraph.

As you can see in this post, I’ve started by telling you exactly what I’ll write about. Right after, I convinced you to continue reading by explaining why it’s valuable to explain things in writing. Otherwise, you’d not have gotten to this paragraph. Then, I started explaining the subject in detail; and will continue to do so for the next couple of sections. Eventually, as you’ll see at the end of this blog post, I’ll summarise everything I’ve taught you.

Also, remember that this structure applies to each sub-unit of your piece. As you write, you should use these three steps in your whole post and each of its sections and subsections, as I just did. Put another way, your pieces should have a fractal structure; the three-step pattern repeats itself within smaller parts of the text.

From concrete stories to abstract facts

It’s easier for readers to process stories and images than for them to process abstract facts. In this section, I’ll demonstrate how examples help and show a few instances in which fiction has helped teach people something.

Imagine you’re explaining a Monte Carlo simulation, for example. Explaining it in mathematical terms is complicated and inefficient. No one ever learned how to do a Monte Carlo simulation by reading its Wikipedia entry.

Instead, it’s much easier to tell a story of how Laplace used a Monte Carlo simulation to estimate pi. Or, even better, how John, the reader’s fictional colleague, used a Monte Carlo Simulation to estimate how likely it was for two people in the office to share the same birthdate.

Sometimes inventing a story might feel silly, but people do learn better with a bit of storytelling.

As I was writing my last book, I felt silly myself by using Louis, a fictional baker in East London, to teach people about software testing.

After writing the first three chapters, I thought to myself: “there’s no depth in Louis. Who do I think I am? Dostoevsky?”.

Luckily, I didn’t erase Louis from my hard drive and submitted the first few chapters for review, including his story.

When I got my reviews back, I was surprised that the vast majority of readers said their favourite part about the book was how helpful and captivating Louis’ story was. The baker had helped them learn better.

Furthermore, creating concrete examples is a great way to get past writer’s block. When you’re telling a story, you don’t have to think much about cold hard facts or how accurate is the information you’re writing. You simply imagine and write.

Great examples of this principle are The Phoenix Project, by Gene Kim, George Spafford, and Kevin Behr and The Goal, by Eliyahu Moshe Goldratt and Jeff Cox. All of those books convey valuable knowledge through fictional stories.

As I’ve done in this section, use concrete examples to explain things. Then, once you’ve used examples, generalise the learnings from those examples, and present them in abstract form.

Format, grammar, voice, and style

Images and other visual aids, jokes, and tone will enrich your text so that it’s not exclusively about pure, distilled facts. In this section, I’ll show you how jokes, visual aids, and style (in this order) can make your text much more entertaining than it would typically be and keep readers hooked.

Take some time to appreciate Randall Munroe’s geniality in the classic story of little Bobby Tables, for example.

This is the perfect comic to illustrate a blog post about SQL injection. In four panels, Randall uses a concrete example to explain what SQL injection is and why it’s important.

Given the comic’s example, more perspicacious readers would perhaps not even need to go through the rest of the blog post to understand SQL injection.

Images like the one above serve as excellent concrete examples and give your readers a bit of a break from slow, dense pieces of text.

Especially on the internet, where people’s attention span is lower, images help to keep them engaged.

Furthermore, when someone opens a link, they’re more likely to stay if they see meaningful visual content. The same principle is valid for books. As I was writing my book, I was told by my publisher that when people browse a store’s books, they’re more likely to buy it if its content is visually pleasing and includes images.

In addition to images, the way you write is paramount to keeping readers engaged. Short sentences are better than long ones. They give readers breathing room and dictate the rhythm at which they read.

As a non-native English speaker who relies on reading experience rather than written rules, I don’t really feel comfortable elaborating that much on punctuation or grammar. Therefore, I’ll delegate to Pinker, William Strunk, and E.B. White the task of teaching these subjects. If you’re willing to read them, I’d recommend A Sense of Style and The Elements of Style.

Finally, I’d like to give you some advice on finding your “voice”. Finding a “voice” is one of those things in literature I’ve never understood that well.

To me, it didn’t feel like authors had voices until I tried to do some writing myself. As I committed pen to paper, I was highly self-critical, and, as I re-read myself, I thought I sounded utterly arrogant. My writing didn’t sound like me at all, or, at least, I didn’t like to think I sounded that arrogant when I talked.

To find my voice, I had to write a lot. Looking back, I think I only found a “voice” after writing a third (approximately two hundred pages) of Testing JavaScript Applications. Writing that much and that frequently helped me merge my talking “voice” with my writing voice.

Now, it feels like I write just like I talk, as Paul Graham would put it. Yet, it took a lot of effort to make it seem effortless. Therefore, if you want to find your voice, you must write a lot and do it often.

As a summary for this last rather fragmentary section, just remember that you can use tools other than writing to keep readers engaged. Those tools are images and visual aids and your voice and style.

Summarising

Now that I’ve told you what I’d explain and explained it, it’s time to tell you (again) everything I’ve just explained.

First, you must remember not to “bury the lede”: as you start your text, tell your readers what you’ll explain. Ideally, you should also inform readers of how you’ll explain it.

As you do that, you should make sure to engage readers so that they go from one paragraph to the next, all the way to the end of your piece. If you need to use jokes, hyperboles, or images to convince someone to keep reading, do that.

After you got readers “hooked”, explain in detail what you promised, no more, no less.

To make explanations more digestible, start with concrete examples and then generalise those examples to abstract pieces of knowledge. Sometimes, inventing a story is a great way to engage readers and get rid of writer’s block.

Finally, after teaching everything you promised, circle back and summarise what you’ve explained, as I just did.