⇐ Words ⇐ ⇑ Course overview ⇑ ⇒ Lists and instructions ⇒
Short is good
Short sentences (less than 20 words) are better than long sentences.
- Short sentences are easier to read.
-
They impose less cognitive load on readers. Long sentences take more attention and can slow readers down. An if they lose their place, there’s more to reread.
- Short sentences are easier to understand.
-
They tend to have simpler grammar. It’s easier to misread a long sentence.
- Short sentences are easier to write.
-
At almost any level of English skill, a short sentence with simple grammar is easier to write than a long one.
Shortening sentences
Given that sentences are the primary building blocks of documentation, it is important that each of them conveys only one single fact, stated as simply as possible, so that the reader can grasp each item completely before going on to the next.
This is a classic first-draft sentence. It’s very long, full of extra words, and wanders from topic to topic. Everything in it is important, but the reader has to work to get that important stuff out. How can you fix this?
First, identify the separate facts in the sentence. They’re marked in with different colors below.
Given that sentences are the primary building blocks of documentation, it is important that each of them conveys only one single fact, stated as simply as possible, so that the reader can grasp each item completely before going on to the next.
Next, cut out any extra words, so that each fact stands out in its sentence. Rephrase unclear or wordy text. This step is really an exercise in word choice.
Given that sentences are the primary building blocks of documentation, it is important that each of them conveys only one single fact, stated as simply as possible, so that the reader can grasp each item completely before going on to the next.
Now turn that long sentence about lots of things into a set of short ones, each about only one thing.
Sentences are the primary building blocks of documentation. Each sentence should convey one fact. This fact should be stated as simply as possible. That way, the reader can learn things one at a time.
What’s between the subject and the verb?
Each sentence in technical writing should contain only one fact.
Part of editing your first draft is hunting down stray facts that need their own sentences. There’s one place where those extra facts often lurk: between the subject (the person or thing that does the action) and the verb (an action word or a linking word like "is").
Find those two parts of the sentence and look at the words between them. Count them.
The Total Perspective Vortex, which is on the planet Frogstar B, displays a model of the entire universe.
In the sentence above, the words between The Total Perspective Vortex and displays are:
which |
is |
on |
the |
planet |
Frogstar |
B |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
Having that many words between the subject and the verb doesn’t always mean there’s a second fact in there. But if you have more than a few words in that space, it’s time ask yourself the question.
In this case, there is a fact in there: the Vortex is on Frogstar B. That’s a different fact than what’s left when you remove those words: the Vortex displays a model of the entire universe. Bring that hidden fact out into its own sentence.
Two facts, two sentences.
The Total Perspective Vortex displays a model of the entire universe. The Vortex is on the planet Frogstar B.
Think about which and that
The Total Perspective Vortex, which is on the planet Frogstar B, displays a model of the entire universe.
The Total Perspective Vortex that is on the planet Frogstar B displays a model of the entire universe.
There’s one thing to be careful of when you use the "count the words and check for a fact" technique.
The two sentences above look almost exactly the same. Just a couple of commas left out, and that instead of which. But they’re very different, and the difference is the subject.
The subject of this first sentence is The Total Perspective Vortex. The way it’s written shows that there’s only one Vortex. The reader doesn’t need any more information to know what you’re talking about.
After stating the subject, the you have two facts about it:
-
It is on the planet Frogstar B.
-
It displays a model of the entire universe.
Two facts, two sentences:
The Total Perspective Vortex displays a model of the entire universe. The Vortex is on the planet Frogstar B.
The subject of the second example is longer. It’s The Total Perspective Vortex that is on the planet Frogstar B. This implies that there’s more than one Vortex, so the you have to tell the reader which Vortex you’re talking about. The "that" clause explains that it’s the one on Frogstar B (so, not one on the planet Traal).
Once the subject is clear, the you have only one fact to document:
-
It displays a model of the entire universe.
Because there’s only one fact, you don’t need to split up the sentence:
The Total Perspective Vortex that is on the planet Frogstar B displays a model of the entire universe.
Cut out phrases
The Arkenstone is on top of the dragon’s hoard under the Lonely Mountain beside the Long Lake.
THE PROBLEM
Each of these pieces of information about where the Arkenstone is looks really useful. But there are so many of them, piled on top of each other, that the reader gets tired and bogged down.
THE SOLUTION
Edit this sentence by cutting down the pile of information. Take it in stages:
-
Leave one phrase in the sentence. The point of that sentence is to tell the reader where to find the Arkenstone.
-
Make another sentence with the next piece of information. You’re feeding your readers facts in bite-sized pieces.
-
Ask yourself how much detail your reader needs at this place in the document. If the section you’re writing is about mounting an expedition to steal the Arkenstone, you may want to move on to who’s going on the trip, what they’re packing, and when they’re leaving. You can put further details about the destination in an appendix, possibly in a more suitable form (like a map).
The Arkenstone is on top of the dragon’s hoard. The hoard lies under the Lonely Mountain. For more information on the route, see the map in Appendix A.
Other improvements
Write active sentences
The Death Star was destroyed by the Rebellion.
THE PROBLEM
English’s natural word order is the subject (the person or thing that does the action), followed by the verb (the action word), then everything else after that.
The sentence above doesn’t follow that natural order. The subject is not The Death Star, but the Rebellion. It was the Rebellion that did the destroying. But the reader has to wait for the end of the sentence for that. Waiting until the end to find out whodunnit works in mystery novels. But in technical writing, it’s more cognitive load.
The marker of this kind of sentence is a passive verb, a verb that says that the Death Star was just hanging around in space, minding its own business, until destruction happened to it. Passive verbs generally use the form [is/was/be] verbed by: was called by, is used by, can be supplied by.
Sometimes there is no by. Passive sentences are also used to hide who did a thing. Politicians love this: Mistakes were made, they say, and it’s a complete sentence. It’s just not a sentence that tells the reader who made those mistakes (spoiler: it’s usually the speaker).
THE SOLUTION
Find out who actually did the thing and put them first. The verb will then move into the active form: called, uses, can supply, destroyed.
The Rebellion destroyed the Death Star.
WHEN TO BREAK THIS RULE GUIDELINE
Now you know the rule. But remember Rule Zero: sometimes clear writing breaks writing guidelines.
There are two cases where a passive sentence is better than an active one:
-
When the topic of the sentence—what the sentence is about—is not its grammatical subject. If I’m writing a history of planet-destroying space stations, I’m more likely to use the first sentence, because the reader’s focus is on the Death Star.
-
When mentioning who did the action will distract the reader. "An error was detected" tells the reader everything they need to know. Saying that the system detected the error tempts the reader to think about the system as well as the error. But it’s the error that’s important.
Clarify references
The tow ship Nostromo encountered a hostile alien on the moon LV-426. It was later destroyed.
THE PROBLEM
What does it refer to here? It could be:
-
The tow ship Nostromo (spoiler: the Nostromo is destroyed in the film.)
-
The hostile alien (spoiler: the alien is destroyed by the end of the film.)
-
The moon LV-426 (spoiler: the moon is not destroyed, which is why there’s a sequel.)
THE SOLUTION
If it’s not absolutely clear what words like it, this, or that refer to, use part or all of the previous term. It’s better to be a little repetitive and completely clear than to leave your readers in doubt.
The tow ship Nostromo encountered a hostile alien on the moon LV-426. The ship was later destroyed.
Phrase things positively
Don’t close your eyes unless there are no weeping angels nearby.
THE PROBLEM
Understanding negative sentences is harder than understanding positive ones. The reader has to mentally tag which parts of a sentence are true and what parts are not. Positive sentences don’t require that work, because everything in them can be treated as true.
THE SOLUTION
-
Try to change negative pieces of information to positive ones (don’t close your eyes becomes keep your eyes open).
-
Check whether the sentence still has the same meaning for the reader. You don’t want to change the content of the text, just the form. Only use the positive sentence if you haven’t changed the meaning.
Keep your eyes open if weeping angels are nearby.
A DEEPER POINT TO CONSIDER
Doing this exercise and comparing the sentences is a good way to think about the scope of your writing.
For example, there’s a case that’s not covered by either sentence: what to do if you don’t know whether or not there are weeping angels nearby.
The first, negative sentence carefully limits what you’re going to talk about. Did you write it this way because what’s outside of those limits is complicated and hard to explain? (How do you detect weeping angels?) Is the negative sentence a sign that you were avoiding the difficult bits when you wrote that first draft?
Does your reader need to know the messy, complicated thing you were avoiding? If so, you need to address that gap, whether or not you change the sentence to be more positive.
If there are conditions, put them first
Honestly, the title kind of says it all. But why does this guideline exist?
Call the police if you know who killed Laura Palmer.
THE PROBLEM
Suppose you have a reader who is in a hurry, and is following the instructions as they read them (and doesn’t know who killed Laura Palmer). You’ve just told them to call the police, so they pick up the phone and dial the emergency number. When they read further and discover that the instruction to call wasn’t meant for them, they’re going to have to hang up.
THE SOLUTION
As the heading says, if there are conditions, put them first. That way a reader who doesn’t know who killed Laura Palmer can skip the second half of the sentence and move on with the documentation.
If you’re know who killed Laura Palmer, call the police.
Exercise
To practice what you’ve just learned, do the word and sentence exercise.
⇐ Words ⇐ ⇑ Course overview ⇑ ⇒ Lists and instructions ⇒