After years of grumpily editing old content, I’ve found that many writers – including myself – have a problem meeting the reader’s needs. The average reader needs a concrete outcome like following a process or learning a new concept. Usually, the overall structure of the content matches that need; technical writers have a sort of blueprint in their heads that leads users from basic information through sequential steps to a useful conclusion. But when you start getting into the details, you find that not every paragraph, not every sentence, has a clear use for the reader, either as relevant background information and context, or as an action they can take. Some information is actually useless to the reader; most is useful but in a non-obvious way.

“Non-obvious” is not a technical writing goal.

So let’s look at how we can use key takeaways and front loading to meet the reader’s needs.

An example, and how to fix it

Here’s an example from a building survey, where the wealth of information is obscuring the fact that the reader isn’t presented with an action:

“Flat roofs have a normal life expectancy of between 10 and 15 years. The flat roof is covered with a bitumen based membrane. It should be noted that the only way to determine whether a flat roof is completely weatherproof is to take core samples. This roof is 20 years old.”

To a reader, this version is more useful:

“You should replace the flat roof as soon as possible. It’s 20 years old, exceeding its life expectancy by five to ten years. We have no useful way of determining whether it’s still weatherproof, so assume from its age that it is not.”

The new version gives the reader an actual action (get a new roof) and a very concrete explanation of why they need to take the action (it’s all about maths and an assumption that cannot be tested).

Note in particular that the action here is to get a new roof, but I’m sure you’ll forgive anyone who read the original paragraph and assumed they should be taking core samples.

So how did we get from the original paragraph to the new version?

Key takeaway and front loading

We start by asking “What is the reader supposed to take away from this paragraph”. In our example, the takeaway is that the roof needs replacing. We emphasise the key takeaway by front loading the information.

Front loading information means starting each sentence and each paragraph with its point, rather than with the buildup to that point. Starting with the point gives the reader something – a hook – on which to hang all the other information we provide. This helps the reader build a picture in their mind as they read. The alternative – back loading – forces the reader to hold abstract information in memory until they find out what it’s describing, which often isn’t until the end of a long paragraph. This is hard, especially for slower readers such as non-native speakers of the language you’re writing in.

The details

The details are how we justify and explain the key takeaway. In our example, we need to justify suggesting the roof replacement. Any information that doesn’t justify or explain the takeaway – such as what the roof membrane is made of – probably doesn’t belong in that paragraph.

The art here is being explicit without too many repetitions. It’s also knowing what not to explain: If a reader is buying a house, we can assume they understand why a non-weatherproof roof is not in their best interest.

The why/so what technique

The easiest way I know to work out what belongs in a paragraph is the “why/so what” technique:

1. For each statement we make, we explain to the reader why reality is like this: “Statement A. Why? Because X. Statement B. Why? Because Z.”
2. When we’ve run out of statements that need explaining (we’ve reached “a house roof should be weatherproof”), we ask “so what”. The “so what” is the key takeaway, the actual action the reader should take. We put that at the front of the paragraph.

All the answers to the “why”s should support the “so what”. If they don’t, they’re not relevant to the key takeaway of this paragraph. Either they need to be taken out, like the membrane information in our example, or they need to support a different takeaway – and the current takeaway needs its own set of supporting statements.

That’s all there is to it. What, then why(s). That’s how we walk a user through the “how” of what they need to do.

Why we get it wrong

Most technical writers don’t read a whole lot of technical writing. This is perfectly reasonable – we’re not constantly learning how to use new software. But it means that the biggest influences on our writing aren’t teaching us how to write technical documentation; they’re teaching us how to write fiction, popular science, biographies and sweeping historical statements. They’re teaching us, at most, how to explain a concept or event. They are not teaching us how to write instructions.

Here’s another example, this one in technobabble:

The value of U4B5 at a point in space is half the value of F67N at this point.

As an instruction, we’ll need to write something like:

We don’t calculate the value of F67N at a point in space from scratch. Instead, we double the value of U4B5 at the same point.

The first sentence is not incorrect, but it’s theoretical, and an instruction in technical writing shouldn’t be theoretical. It should answer “how”, not “what”.

“But what if this wasn’t ever intended as an instruction?” I hear you type. “Maybe it’s a concept, some background info or a deep dive. Not everything we write in technical documentation is a process the user should follow.”

I respectfully disagree. All technical documentation, even the background info and the deep dives, is ultimately intended to help users accomplish a goal, even a vague “take over the world” kind of goal. Therefore, even when we know the user isn’t likely to ever try this at home, we should be explicit about how they could.

Conclusion

Not writing explicit instructions is possibly the hardest habit to break. The language of concepts and vague connections is quite natural, whereas the why/so what technique can leave you feeling a bit staccatoish. But for a reader, the natural flow of information makes up for the less natural flow of language. Technical writing isn’t poetry.