Be concise

Print topic Print topic Previous topic  Next topic

Omit all words and syllables that are nothing but empty calories.

Every word and character saved is a step toward more clarity. The only exception to this rule is: Don’t be concise at the expense of clarity. If you need more words to be more specific or to avoid ambiguity, go ahead and include them (see Add syntactic cues, Be clear about what you’re referring to, and Feel free to repeat a word).

The key to avoiding empty calories in your documents is to be aware why you may be tempted to add them:

When you aren’t sure about the facts that you describe, you might be tempted to conceal your uncertainty by adding something vague.

You might be tempted to impress your readers with your sophisticated language skills or with your profound domain knowledge.

You might be tempted to impress your boss with the number of pages that you’ve produced.

You might be tempted to impress customers with the number of pages because you think that a big manual makes your product look like it’s worth the money.

You just don’t care and write down something quickly because you don’t like writing manuals and want to complete this task as soon as possible.

Resist these temptations.

No:

The program can handle the following four file formats: A, B, C, and D.

Yes:

The program can handle the file formats A, B, C, and D.

(In this sentence, the relevant fact is which file formats the program supports. The number of formats (“four”) is irrelevant, so leave it out. Also you can leave out the phrase “the following” without any loss of information.)

No:

The new car is faster and will break down less often.

Yes:

The new car is faster and more reliable.

No:

The cable is about 10 meters in length.

Yes:

The cable is 10 meters long.

No:

It has a rectangular shape.

Yes:

It’s rectangular.

No:

You should have some experience within a Unix environment.

Yes:

You need to have some Unix experience.

No:

If you’re a user who has experience in this field, use expert mode.

Yes:

If you’re an experienced user, use expert mode.

No:

The program isn’t able to print.

Yes:

The program can’t print.

No:

It’s necessary to enter a value.

No:

You’re required to enter a value.

Yes:

You must enter a value.

No:

You can format the table by means of the toolbar.

Yes:

To format the table, use the toolbar.

No:

In order to print the file, choose the menu command File > Print.

Yes:

To print the file, choose File > Print.

No:

It takes a longer period of time to write a user manual than to read it.

Yes:

It takes longer to write a user manual than to read it.

 


Talk to the reader

Use the active voice

Don’t say “please”

Make short sentences

Avoid parentheses and nested sentences

Feel free to start sentences simply

Feel free to end sentences simply

Use short, common words

Watch for “…ed”

Watch for “the … of” and for “of the”

Watch for opening “It …” and “There …”

Use contractions

Use strong verbs

Avoid gerunds that conceal a direct verb

Blacklist: Overblown words

Blacklist: Filler words