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.
|