⇐ ⇐ ⇑ Course overview ⇑ ⇒ Sentences ⇒

Words matter

a globe filled with words

It almost goes without saying that words are the building blocks of technical writing.

Choose your words well, and your readers will find the documentation easy to understand. They won’t even notice how clear and well-defined its ideas are, how smoothly it teaches new vocabulary and concepts, or how pleasant it is to read.

Choose your words badly, and your readers will be confused, tired and frustrated, without quite knowing why.

Use a consistent dialect

English has many dialiects, but for technical writing purposes, what really matters is whether you’re writing in US English or UK (and Commonwealth) English. The difference to focus on between the two is spelling.

US English UK English

color

colour

center

centre

initialize

initialise

It’s important to spell consistently throughout your documentation. Mixed-dialect documentation does more than just look inconsistent. It also breaks search functionality and leads to broken links. Your style guide should specify which dialect to write in.

If your tooling includes spell checking or grammar checking set it to the correct dialect.

This course uses US English.

Note
 If you’re documenting software, be consistent with the dialect that the software itself is written in. Otherwise in-code terms such as variable and module names will look odd and break search.

One word, one meaning

The words you use should have a 1:1 relationship with the concepts they represent. This means that every word should be used to mean only one thing. If you want to talk about a different thing (even a subtly different one), use a different word.

We replaced the hyperdrive coil with a better model. One of the magnetic bolts in the new coil was defective, so we had to replace it.

THE PROBLEM

In the example above, replace is used to mean two things:

  • Take something out and put a better version in.

  • Take something broken out and put something in that’s the same version, but not broken.

If you’ve been use the word to mean both things, when you tell your reader to replace something, they won’t know which version of the thing to use.

THE SOLUTION

  1. Choose one meaning to associate with the original word: Take something broken out and put something in that’s the same, but not broken.

  2. Find another word for the other meaning. In this case, you can use upgrade for take something out and put a better version in. If you don’t know any more words, try a thesaurus1.

  3. Write these decisions down on your word list.

  4. Apply them throughout the document.

We upgraded the hyperdrive coil. One of the magnetic bolts in the new coil was defective, so we had to replace it.

Caution
 Watch out for words that are are spelled the same but sound different. If you record things in a database, maybe they should be entries rather than records.

1. A website where you can enter a word and find other words that mean the same thing.

One meaning, one word

The 1:1 relationship goes the other way as well. Each concept should be referred to by only one word. Unlike in other kinds of writing, varying your word choice isn’t interesting; it’s cognitive load.

When interrogating suspects who may have breached the Matrix, bring two folders into the room. One file should be full and the other nearly empty.

THE PROBLEM

Image of a file folder

The sentences above mention a folder and a file. But both words refer to the same thing: a piece of stiff brown paper folded in half, into which you put other pieces of paper.

If you use two words, some of your readers will think you mean two things, and start trying to find a distinction that isn’t there. Picture your reader staring at a stationery cupboard, looking for something that can be described as a file but isn’t what they already know is a folder.

THE SOLUTION

  1. Choose one word to use for each idea or concept. In this case, folder.

  2. Write this down on your word list.

  3. Apply it throughout the document.

When interrogating suspects who may have breached the Matrix, bring two folders into the room. One folder should be full and the other nearly empty.

Note
 When you’re deciding which concepts are different enough to need their own words, think about the reader. If reader won’t see a difference, use the same word. So if a reader doesn’t need to know what tree is an oak and what is a pine, call them all trees.

Why are you using this term?

After the Burn, the Federation had only twelve warp-capable Intrepid, Eisenberg and Armstrong-class ships.

THE PROBLEM

Every time you use a technical term, you’re imposing cognitive load on any readers who don’t already know it. Ask yourself if it’s worth it.

Technical terms can become a kind of geek gang sign, used to show off the writer’s expertise. You may feel that it builds reader trust in you. But a better way to show that expertise is to explain a difficult thing clearly.

THE SOLUTION

Only use rare and specific technical terms when they make a useful distinction that more common words don’t. If you must use them:

  1. Introduce it properly (see [_introducing_new_terms]).

  2. Write it down on your word list.

  3. Apply it throughout the document.

  4. If you have a glossary, add the word to it.

After the Burn, the Federation had only twelve starships.

Note
 An example is the definition of the term thesaurus in the section on One word, one meaning. THe footnote defines it as A website where you can enter a word and find other words that mean the same thing. There’s a techncial term for a word that means the same thing as another word. It’s a synonym. But using that word would have meant teaching it to readers, although it’s never used again in the course. That’s wasted energy. Cognitive load.

Keep terms in their original forms

USING THE NEURALIZER
Always neuralize civilians if they’ve witnessed an alien event.

THE PROBLEM

If you introduce a term in one form, then use it in another, the reader has to do some mental work to follow the transition. Sometimes it’s a small transformation and not much work. Other times, your reader can barely figure out what you mean. But it’s all cognitive load.

It also affects search results and adds a maintenance problem. If your company switches from the Neuralizer to the Brain-E-Race, updating your documentation is harder and more error-prone..

THE SOLUTION

Treat terms the way you’d treat the names of people: spell them correctly and consistently. Only use them in their original (canonical) form.

Unsurprisingly, your word list will help you with this.

USING THE NEURALIZER
Always erase civilians' memory with the Neuralizer if they’ve witnessed an alien event.

Introduce new terms

New words

Envoys communicate with the Ekumen using their ansibles. They are not required to file regular reports.

THE PROBLEM

When they meet a term they don’t know, readers have to guess its meaning from context. If they can’t guess, they have to interrupt their flow to go look the word up. Both of these are cognitive load.

THE SOLUTION

  1. Define the term immediately after the first time you use it.

  2. If you have a glossary, use the same definition there.

  3. Use your word list (surprise!) to keep track of this

The real trick, of course, is figuring out which words your readers are likely to understand. You should think about this from the planning stage onward.

Envoys communicate with the Ekumen using their ansibles. An ansible is an instantaneous communication device. Envoys are not required to file regular reports.

New abbreviations

Requests from S.H.I.E.L.D should be given the highest priority. The head of the Division has Top Secret ULTRA access.

THE PROBLEM

Abbreviations have the same problem as technical terms: readers may not know what they mean. They can also can overloaded, meaning that the same acronym or initialism can mean more than one thing. Does FTP mean file transfer protocol or free-to-play?

THE SOLUTION

Write out the entire term on first use. Then put the abbreviation in parentheses immediately after it. Afterwards, use the abbreviation consistently.

Requests from the Strategic Homeland Intervention, Enforcement and Logistics Division (S.H.I.E.L.D) should be given the highest priority. The head of S.H.I.E.L.D has Top Secret ULTRA access.

There are several different types of abbreviation, but they should all be treated the same way.

  • acronyms, where you say the first letters of the words as though they were a word (NASA).

  • initialisms, where you say the names of the letters (URL).

  • portmanteaux, made up of parts of different words stuck together (turducken).

Note
 Your style guide may have rules for how you capitalize and punctuate acronyms and initialisms (for example, all capital letters but no periods in between). If the acronym or initialism has an official style (as S.H.I.E.L.D. does), then use that even if it clashes with the style guide.

Getting the tone right

An adult (actor Steve Buscemi) dressed as a teenager, captioned 'How do you do, fellow kids?'

Writing does more than convey information. Its tone tells the reader who you are (formal or friendly?). And tone can affect cognitive load. A few basic rules for getting tone right:

Yeet the slang

Slang doesn’t travel or age well. What’s clever and amusing for one audience, in one place and at one time, is just embarrassing elsewhere. (It can also be actively offensive.)

Eschew excessively abstruse vocabulary.

Avoid overly rare words.

Just don’t say easy. It’s simple!

It’s tempting to reassure your readers that what you’re talking about isn’t difficult. But you won’t always know what those readers find difficult. If they can’t do or understand something that you say is easy (for example, because the configuration instructions weren’t clear), they’re going to feel judged.
Show them that something is easy by writing about it clearly.

No need for please.

You want your readers to do things, so surely telling them to please do it is good, right?
Not really. Asking someone to please do things is a personal request. It can feel too personal. Give your readers a little more space. You can tell them what to do without begging.

It’s OK to use contractions, but don’t overdo it.

This depends on your style guide, tone, and audience. But if your writing is sounding stiff and robotic, consider using contractions. Particularly useful are the negative ones, such as doesn’t/don’t, can’t, and shouldn’t.+ Note that contractions aren’t appropriate in very formal documents. And never smush more than two words together (shouldn’t’ve).

Write neutrally

Gender neutral symbol

There are things you know, such as your audience’s role and their goals or the documentation topic. But there are also a lot of things you don’t know, don’t need to know, and shouldn’t assume:

What culture someone’s from

We work in increasingly multicultural settings. Reflect that in the examples you use. If you’re using names, pick ones from multiple genders, cultures, and places. Don’t assume that your readers share the dominant religion or culture of the place you live.

What gender someone is

Not all engineers are male. Not all of any profession is any given gender. So don’t use gender-specific pronouns when you talk about people. What do you do instead?

  • Use gender-neutral vocabulary: chair rather than chairman, actor in place of actress, work hours instead of man hours.

  • Instead of he, his, and him, either:

    • Use they, their, and them, with the verb (action word) that goes with it. So When an engineer sees a problem, he solves it. becomes When an engineer sees a problem, they solve it. It’s called the singular they, and it’s actually been in use in English for centuries.

    • Move the whole thing into the plural: When engineers see problems, they solve them.

(Don’t use he or she, he/she, or s/he. They’re distracting.)

⇐ ⇐ ⇑ Course overview ⇑ ⇒ Sentences ⇒