Be specific

Print topic Print topic Previous topic  Next topic

When reading instructions, users are looking for clear answers.

Don’t be vague.

Don’t be ambiguous.

You know the product that you’re describing—readers don’t. What’s clear to you may not be clear at all to your audience. Also, bear in mind that most readers don’t read manuals from start to finish, so they only see a small part of the whole.

Unclear or ambiguous text has a serious impact on the perceived quality of your document:

If readers do notice that a phrase is unclear or ambiguous, this results in uncertainty. Ambiguous texts don’t inspire confidence.

If readers don’t notice that a phrase is unclear or ambiguous (which often happens), this may result in misunderstanding and failure.

If an unclear or ambiguous phrase goes unnoticed by translators, translated versions of your document may be plain wrong. In this case, all readers who read the translated version get the wrong information.

The key rule on how to be specific is to avoid all sorts of vague terms.

Note:
Being specific is more important than being concise (see Be concise). Don’t write ambiguous sentences because you want to make them as short as possible. If necessary, don’t hesitate to repeat a word, or add a syntactic cue (see Feel free to repeat a word and Add syntactic cues).

No:

If you’ve filled in all fields correctly, the results window should appear.

Yes:

If you’ve filled in all fields correctly, the results window appears.

(If you doubt that your product works as intended, don’t show your doubt to the reader. Always describe the intended behavior or usual condition.)

No:

The action should be finished quickly.

Yes:

You need to finish the action within one minute.

No:

The program can also import a number of other formats.

No:

The program can also import Word files, etc.

Yes:

The program can also import Word files, PDF files, and XML files.

No:

If necessary, turn the lights on.

Yes:

If it’s dark and the lights are off, turn them on.

No:

between 7 and 11

(Unclear: Are 7 and 11 included?)

Yes:

from 7 through 11

No:

The file set includes common files that are used in many web applications.

Yes:

The file set includes files that are shared between web applications on the web server.

or:

The file set includes files that many web applications typically use.

No:

We will successfully install your washing machine.

Yes:

We will unpack your washing machine, set it up, connect it, and get it working.

No:

Press any key to continue.

Yes:

Press [Enter] to continue.

(Note: Name a specific key even if other keys will do the same job. For users, it’s faster to look for the [Enter] key than having to choose a key by themselves. In addition, it prevents any feeling of uncertainty.)

Expand /Collapse All Subsections

Typical examples of vague terms

and so on

and/or

can

corresponding

etc.

may

maybe

object

ought to

quite

rather

respectively

should

some

 


Don’t mix subjects

Watch the position of modifiers

Feel free to repeat a word

Add syntactic cues

Be clear about what you’re referring to

Use “then” with care

Use “and” with care

Don’t use “(s)”

Don’t use “and/or”

Always use the same terms

Avoid buzzwords

Blacklist: Filler words

can / may / might / must / should