Active voice

Active voice makes your writing concise, direct, and engaging. It also helps the reader identify the subject of the sentence. In the following example, the person who submits the form is essential information. Omitting that leads to a confusing and impersonal sentence.

Passive: The Tobacco Waiver form must be submitted to the appropriate representative.

Active: Submit the Tobacco Waiver form to Human Resources.

The passive almost always results in a longer sentence. Passive voice de-emphasizes who should take an action. Wordy instructions are also harder to follow.

Passive: The JIRA notice should be saved in your email, as it will be required for future inquiries.

Active: Save the JIRA notice in your email folder for later use.

When in doubt, cut directly to the verb and give the reader clear directions.

How to recognize the passive voice

Use of the passive voice is common enough that many people don't notice when they use it. Here's a simple way to recognize it. If you insert by zombies after the verb and the sentence still makes sense, you're using the passive voice.

The form was submitted by zombies.

Ted's oatmeal cookies were consumed by zombies.

When to use the passive voice

There are always exceptions. Don't use the passive voice in a way that makes actions seem like they happen without anyone doing them. Good documentation should always make it clear who (or what) is doing something.

You may need to use the passive voice with error messages or make something easier to understand.

Rewording any of these sentences to use the active voice would complicate the sentence or pull focus away from its main point:

Responses sent from JIRA include Waiting for Support and Closed.

Support is required to respond to requests within 4 working hours.

The system was put into an error state by an incorrect entry.