Active voice

In general, use active voice (in which the grammatical subject of the sentence is the person or thing performing the action) instead of passive voice (in which the grammatical subject of the sentence is the person or thing being acted upon), although there are exceptions. Make clear who's performing the action.

In passive voice, it's easy to neglect to indicate who or what is performing a particular action. In this kind of construction, it's often hard for readers to figure out who's supposed to do something (such as the reader, the computer, the server, an end user, or a visitor to a web page).

Recommended: Send a query to the service. The server sends an acknowledgment.

Not recommended: The service is queried, and an acknowledgment is sent.

It's possible to indicate who's performing the action in passive voice (using by), but the resulting prose is generally not as good as if you were to recast the sentence as active voice. So whenever possible, make the doer the subject of the sentence.

Recommended: Send a query to the service. The server sends an acknowledgment.

Not recommended: The service is queried by you, and an acknowledgment is sent by the server.

For more information, see Active voice vs. passive voice in Google's Technical Writing One guide.

Exceptions

In certain cases, it's okay to use passive voice. For example, passive can be okay in the following instances:

  • To emphasize an object over an action.
  • Recommended: The file is saved.

  • To de-emphasize a subject or actor.
  • Recommended: Over 50 conflicts were found in the file.

    Not recommended: You created over 50 conflicts in the file.

  • If your readers don't need to know who's responsible for the action.
  • Recommended: The database was purged in January.