Talk to the reader

Print topic Print topic Previous topic  Next topic

 1  Talk to the reader directly (“You can ….”). Talking directly to the reader increases attention and avoids ambiguity (see also Use the active voice).

Don’t use the passive voice (“… can be done.”).

Don’t talk about the user (“Users can ….”). Don’t use phrases with “one” (“One can ….”).

Don’t be afraid of giving commands. It’s your job to tell your readers clearly what to do.

Write as though you were talking to your readers in a friendly, straightforward way (conversational style). Keep it simple, make short sentences, and use the same short, everyday words that you use when talking to co-workers.

When giving recommendations, it’s acceptable to use we. Don’t use the passive voice to avoid the editorial we. Often, however, the best solution is to create a sentence with you.

Exceptions:

 2  If you’re writing for developers or for administrators, use second person to refer to your reader (the developer or administrator), but use third person to refer to the reader’s end user.

 3  In error messages and troubleshooting information, it can be more polite to use a passive construction rather than to tell users right away that a problem is their own fault (see Errors).

 4  In tutorials, a passive construction is sometimes appropriate to distinguish general information from a prompt to act.

Expand /Collapse All Subsections

Examples    1 

No:

The button must be pressed.

No:

The button must be pressed by the user.

No:

Users must press the button.

No:

One must press the button.

Yes:

Press the button.

No:

The Print dialog provides the possibility to change the printer settings.

Yes:

In the Print dialog, you can change the printer settings.

No:

In this section, the installation of the program will be shown.

Yes:

In this section, we show you how to install the program.

Top:

In this section, you’ll learn how to install the program.

No:

It’s recommended to use a shielded cable.

Yes:

We recommend using a shielded cable.

Top:

For best performance, use a shielded cable.

Examples    2 

No:

Administrators can reset passwords so that users are able to create a new password.

No:

Passwords can be reset so that users are able to create a new password.

Yes:

You can reset passwords so that users are able to create a new password.

Examples    3 

No:

You’ve made a serious mistake. Next time, read the manual before you try this.

Yes:

A mistake has been made. More information can be found in the manual.

Examples    4 

No:

To make a phone call, type the telephone number. Now you try it: Type a friend’s telephone number.

Yes:

Phone calls are made by typing the telephone number. Now you try it: Type a friend’s telephone number.

 


Writing procedures

Use the active voice

Use strong verbs

Don’t say “please”