IMPORTANT: This topic is about active vs. passive voice. However, all of the following examples contain discussions of multiple subjects—not just active vs. passive voice. Therefore, in addition to active vs. passive voice, you are going to learn a lot of different things about good writing and rewriting.

Example 1

REWRITE THIS SENTENCE

PROBLEM

Active voice is more forceful and clear than passive voice. Active voice should always predominate in technical writing. Readers prefer it. Passive voice should be the exception, not the rule.

There are certain situations where passive voice is the preferred construction. But in this example, there is no reason why we cannot rewrite our problem sentence in the active voice.

DISCUSSION

Our problem sentence has the passive voice construction, is used. The obvious question is—is used by whom or by what? Is it a person, a machine, or a process? Don’t you think that is an important piece of information?

Who is the actor? Who uses the resource template?

The problem sentence happens to be plucked out of a procedural sequence. The intended subject in this case is second-person singular; that is, You is the subject of the sentence. You are the user.

Here is the deal with passive-voice sentences: the subject of the sentence typically is omitted from the sentence.

To illustrate, in our problem sentence, the second-person singular You is understood in the passive-voice construction. If you make the subject explicit in our passive-voice sentence, this is what it looks like:

The resource template is used by you for the path portion of the URI.

Ugly. Don’t do that!

However, once you know for sure who or what is the actor, you can convert a passive-voice sentence to active voice.

Remember, it is the same subject (that is, You) whether the sentence is written in the active voice or the passive voice. The spoken You is the subject of an active voice sentence, while the unspoken You is the subject of the passive-voice sentence.

REVISION

Before

The resource template is used for the path portion of the URI.

After

You can use the resource template for the path portion of the URI.

Example 2

REWRITE THIS SENTENCE

PROBLEM

Two problems:

We need to change the passive voice to active voice.
The word order is awkward, so let’s see if we can rearrange the words.

DISCUSSION

Passive to Active Voice

Instead of this:

the operation is executed on all objects

Say this:

the system executes the operation on all objects

Word Order

Instead of this:

even if one of the operations fails due to a CMS error

Say this:

even if a CMS error causes one of the operations to fail

REVISION

Before

If set to true, the operation is executed on all objects, even if one of the operations fails due to a CMS error.

After

If set to true, the system executes the operation on all objects, even if a CMS error causes one of the operations to fail.

Example 3

REWRITE THIS SENTENCE

PROBLEM

The sentence is in the passive voice. Make it active voice.

DISCUSSION

Who or what in the sentence is doing the supporting? Easy. The API management gateway.

The API management gateway is the actor in the sentence.

REVISION

Before

The following system-defined reserved variables are supported by the API management gateway.

After

The API management gateway supports these system-defined reserved variables.

Example 4

REWRITE THIS LIST

PROBLEM

Do the following:

Divide the first bullet point into two bullet points
Change the passive voice to active voice

DISCUSSION

This is a complicated description. In this scenario, three different actors do the patching:

You, the user
The system admin
Scripts

First Bullet Point

This is the first bullet point:

Instances spawned from FakeCorp AMIs can be configured to auto-patch during defined windows or be patched by system administrators from enterprise tools.

Divide it into two bullet points:

Instances spawned from FakeCorp AMIs can be configured to auto-patch during defined windows
[Instances spawned from FakeCorp AMIs] can be patched by system administrators from enterprise tools.

Change both bullet points to active voice (see the following Revision section).

Second Bullet Point

Change it to active voice (see the Revision section).

Use the Can Do Something Construction or the Future Tense

We are talking about features that are not available to the user now, but will be in the future. You can use the future tense or the Can Do Something construction.

REVISION

Before

Future solutions to meet security criteria may include:

- Instances spawned from FakeCorp AMIs can be configured to auto-patch during defined windows or be patched by system administrators from enterprise tools.
- Instances from non-FakeCorp AMIs will be configurable by FakeCorp-supplied configuration scripts to auto-patch during defined windows.

After

Future solutions to meet security criteria may include the following enhancements. During defined windows:

- You will configure instances spawned from FakeCorp AMIs to auto-patch
- System administrators will use enterprise tools to patch
- FakeCorp-supplied configuration scripts will configure instances from non-FakeCorp AMIs to auto-patch

Future solutions to meet security criteria may include the following enhancements. During defined windows:

- You can configure instances spawned from FakeCorp AMIs to auto-patch
- System administrators can use enterprise tools to patch
- FakeCorp-supplied configuration scripts can configure instances from non-FakeCorp AMIs to auto-patch

Example 5

REWRITE THIS SENTENCE

PROBLEM

Two instances of the passive voice in one sentence—amazing!

DISCUSSION

This sentence has two different actors:

The system initiates the default client configuration attributes for the notification message.
The user creates the message.

Now that you know who and what does the acting, rewrite the sentence.

REVISION

Before

The default client configuration attributes for the notification message are used when the message is created.

After

The system uses the default client configuration attributes for the notification message when the user creates the message.

Example 6

REWRITE THIS SENTENCE

PROBLEM

Here is the checklist of things to fix:

Passive voice
Present vs. future tense
Punctuation
Simple sentences
Word order

DISCUSSION

Passive Voice

This passage contains an example of passive voice (the passive-voice verb form is in boldface type):

in most cases we will choose to accumulate one or more errors to be returned

One or more errors are returned by whom or what? Who or what is the actor in this instance?

The system is the actor. Therefore, rephrase it to make that clear.

Present vs. Future

This passage uses the future tense:

in most cases we will choose to accumulate

This activity happens now. It will continue to happen in the future, also. Since it happens both now and in the future, use the present tense.

Punctuation

Same passage:

in most cases we will choose to accumulate

Add a comma after the word cases. The words in most cases form a dependent clause. Always add a comma after an introductory dependent clause.

Simple Sentences

The example sentence expresses three distinct ideas:

The UserControllerExceptionHandler handles situations where we throw a UserControllerException.
Typically, this contains a single, short-circuiting UCError.
However, most of the time after we go through a complete request process flow, we prefer to have the system return one or more errors in addition to data payloads.

Divide the example into the three simple sentences in your rewrite.

Word Order

You correct the awkward word order when you fix the passive voice.

Also, this word order:

in most cases we will choose to accumulate one or more errors to be returned in addition to data payloads after going through a complete request process flow.

Is corrected to read:

most of the time after we go through a complete request process flow, we prefer to have the system return one or more errors in addition to data payloads.

The process flow is the first thing to happen. The results follow the completion of the process flow. Make your language reflect the natural course of events.

REVISION

Before

While the UserControllerExceptionHandler handles situations where we throw a UserControllerException, typically containing a single, short-circuiting UCError, in most cases we will choose to accumulate one or more errors to be returned in addition to data payloads after going through a complete request process flow.

After

The UserControllerExceptionHandler handles situations where we throw a UserControllerException. Typically, this contains a single, short-circuiting UCError. However, most of the time after we go through a complete request process flow, we prefer to have the system return one or more errors in addition to data payloads.

Example 7

REWRITE THIS SENTENCE

PROBLEM

The example sentence has two basic problems:

Word order
Passive voice

DISCUSSION

Word Order

Before you can accomplish something, you need to pick up the tool to do the work. In the real world, this is the natural order of events. Action precedes the accomplishment.

This sentence is awkward because the author puts the accomplishment (that is, the identification of the NRT account) before pointing out what tool to use (that is, using the /validate API).

The example sentence may not look like it, but it could easily be a procedure. It is explaining how to identify an NRT account. For a step, this is the recommended word order:

Use the /validate API to identify an NRT account.

If you simply want to write a descriptive sentence and not a step, say this:

You can use the /validate API to identify an NRT account.

Passive Voice

The example sentence is an excellent demonstration why grammarians inveigh against the passive voice so much. Here it is again:

An NRT account can be identified using the /validate API.

Don’t write in such a roundabout, mealy-mouthed way. Just cut to the chase—be direct, and then move on to the next sentence.

REVISION

Before

An NRT account can be identified using the /validate API.

After

[Description]

You can use the /validate API to identify an NRT account.

Or better

[Step]

Use the /validate API to identify an NRT account.

Example 8

REWRITE THIS SENTENCE

PROBLEM

Passive voice.

DISCUSSION

This sentence is doubly awkward. Not only is it in the passive voice, but it seems to go out of its way to hide the true identity of the actor. Of course, the actor is the new guest. The new guest does his or her own signing-in on the registration page. However, the sentence obscures this obvious fact.

REVISION

Before

Signing in a new guest for the first time is done by using the registration page.

After

The new guest uses the registration page to sign in for the first time.

The new guest signs in for the first time by using the registration page.

Example 9

REWRITE THIS SENTENCE

PROBLEM

This sentence is a procedure, but you would never know it by the passive voice construction.

DISCUSSION

A plan is required by whom? In this case, you are the actor. It is you who must make a plan.

Remember, a passive voice sentence goes out of its way to hide the identity of the actor. That is certainly the case with the example sentence.

IMPORTANT: You must always put a procedure (that is, a step) in the active voice. Never forget that.

REVISION

Before

If the override is still dependent, a plan is required for the retirement of the override.

After

If the override is still dependent, retire the override.

Example 10

REWRITE THESE SENTENCES

PROBLEM

Change the passive voice to active voice.

DISCUSSION

Don’t say this:

Some emails … can be customized….

In order for logins from Facebook to be supported….

Confluence access is required….

Say this:

You can customize some emails….

To support logins from Facebook….

You must have access to Confluence….

REVISION

Before

Some emails seen by users as part of registration, login, account recovery, or permissions, can be customized.

In order for logins from Facebook to be supported, specify values in the client configuration.

Confluence access is required to use this resource.

After

You can customize some emails seen by users as part of registration, login, account recovery, or permissions.

To support logins from Facebook, specify values in the client configuration.

You must have access to Confluence to use this resource.

Example 11

REWRITE THIS SENTENCE

PROBLEM

Passive voice.

DISCUSSION

First Instance

Don’t say this:

The Client ID request form is required….

Say this:

You must submit the Client ID request form….

Second Instance

Don’t say this:

…before the Client ID provisioning process can begin.

Say this:

…before you begin the Client ID provisioning process.

REVISION

Before

The Client ID request form is required before the Client ID provisioning process can begin.

After

You must submit the Client ID request form before you begin the Client ID provisioning process.

Example 12

REWRITE THIS SENTENCE

PROBLEM

Passive voice.

DISCUSSION

Don’t say this:

This parameter is ignored [by whom or what?]….

Say this:

The system ignores this parameter….

REVISION

Before

This parameter is ignored when you create a user account, but required for an NRT account.

After

The system ignores this parameter when you create a user account, but requires the parameter for an NRT account.

The system ignores this parameter when you create a user account, but requires it for an NRT account.

Example 13

REWRITE THIS SENTENCE

PROBLEM

Change the passive voice to active voice.

DISCUSSION

First Instance

Don’t say this:

… when the data for a guest account is changed….

Say this:

… when you change the data for a guest account….

Second Instance

Don’t say this:

…the profile data is deleted

Say this:

…you delete the profile data

REVISION

Before

This section describes the flow that occurs when the data for a guest account is changed or the profile data is deleted.

After

This section describes the flow that occurs when you change the data for a guest account or you delete the profile data.

Example 14

REWRITE THE SECOND SENTENCE (IN BOLD)

PROBLEM

Two things:

Use the active voice.
Don’t wait until the end of a long sentence to identify the tool that works in this situation. Tell the user what tool to pick up and use for the desired action, and then describe the action.

DISCUSSION

Active Voice

Question: Who or what is doing the action? Answer: You are.

Write accordingly.

Word Order

When you write a procedure, first tell the reader what tool to pick up and use before you tell the reader what to do with the tool. In this situation, tell the reader the tool to use is Content Migrator 4.2. This is how you say it:

…you can use Content Migrator 4.2 to import into a 4.2 system the data exported from earlier Publisher versions.

REVISION

Before

Content Migrator 4.2 is not compatible with earlier versions of Publisher. However, data exported from earlier Publisher versions using the appropriate version of Content Migrator can be imported into a 4.2 system using Content Migrator 4.2.

After

Content Migrator 4.2 is not compatible with earlier versions of Publisher. However, you can use Content Migrator 4.2 to import into a 4.2 system the data exported from earlier Publisher versions.

Example 15

REWRITE THIS SENTENCE

PROBLEM

These issues:

Passive voice
Overly formal, stilted language

DISCUSSION

Passive Voice

We have been over this point many times on Grammaticus. When the author says, care must be taken, who or what is supposed to take care? Who is the action agent? Who is the star of this blockbuster movie?

The answer, of course, is You. Use the second person singular.

See the Revision section for the active voice rewrite.

Formal, Stilted Language

Don’t say this:

prior to

Say this:

before

Don’t say this:

care must be taken to adhere to

Say this:

make sure you follow

Word Order

Don’t say this:

the exported file may be manually manipulated

Say this:

you can manipulate the exported file manually

REVISION

Before

Though the exported file may be manually manipulated prior to being imported, care must be taken to adhere to the rigid format requirements.

After

Though you can manipulate the exported file manually before you import, make sure you follow the rigid format requirements.

Example 16

REWRITE THIS SENTENCE

PROBLEM

Fix these problems:

Passive voice
Run-on sentence
Awkward word order

DISCUSSION

Passive Voice

Don’t say this:

What is displayed in the call history window is a list of supported API methods….

Say this:

A list of supported API methods appears in the call history window.

Or better:

The call window shows a list ofsupported API methods.

Simple Sentences

Divide the sentence into two sentences. Please see the Revision section for the rewrite.

Word Order

The word order is improved when (a) you change the passive voice to active voice and (b) when you divide the example sentence into two sentences.

REVISION

Before

What is displayed in the call history window is a list of supported API methods, which are described throughout the site.

After

A list of supported API methods appears in the call history window. These APIs are described throughout the site,

Or better

The call history window shows a list of supported API methods. These APIs are described throughout the site,

Example 17

REWRITE THESE SENTENCES

PROBLEM

More passive voice sentences.

DISCUSSION

Question: In the first sentence, who or what does the providing? Answer: The system. We know this because of the temporary system-generated display name.

Question: In the second sentence, who or what does not review an unmoderated namespace. Answer: A moderator.

Also, in the second sentence, I prefer the usage of the verb is over the verb becomes. However, either verb is acceptable.

REVISION

Sentence 1

Before

Until moderation is completed, a temporary system-generated display name is provided.

After

Until you complete your moderation, the system generates a temporary display name.

Sentence 2

Before

An unmoderated namespace is not reviewed by a moderator before it becomes active.

After

The moderator won’t review an unmoderated namespace before it is active.

Example 18

REWRITE THIS SENTENCE

PROBLEM

Passive voice, wordiness, and usage.

DISCUSSION

Passive Voice

Don’t say this:

If a CMS solr search service is not desired

Say this:

If you don’t want a CMS solr search service

And don’t say this:

the service can simply be disabled in the CMS properties file

Say this:

disable the service in the CMS properties file

Wordiness

The excess verbiage is in brackets:

If a CMS solr search service is not desired, [the service can simply be disabled] in the CMS properties file.

See the Revision section for a more direct way to say the same thing.

Usage

Don’t say desire. It is a loaded word. Say want.

The word desire has connotations not desirable in technical writing. The simple English verb form to want is sufficient.

REVISION

Before

If a CMS solr search service is not desired, the service can simply be disabled in the CMS properties file.

After

If you don’t want a CMS solr search service, disable the service in the CMS properties file.

Example 19

REWRITE THIS SENTENCE

PROBLEM

Passive voice.

DISCUSSION

Don’t say this:

…for the final commit to be completed.

Say this:

…to complete the final commit.

REVISION

Before

The autoCommit settings can reduce the time required for the final commit to be completed.

After

The autoCommit settings can reduce the time required to complete the final commit.

Example 20

REWRITE THIS SENTENCE

PROBLEM

Things to fix:

Passive voice
Use English words instead of i.e. (this is my personal preference)
Use before instead of prior to (this is my personal preference)
To improve readability, break the sentence into two sentences
Avoid using parentheses when the information enclosed is not trivial

DISCUSSION

Passive Voice

Someone or something is the actor in this sentence. Who or what might that be? We learn that “Two new APIs are available for working with temporary files.” Available to what or to whom? Why, it is you, dear reader. Since you are the star of the example sentence, let’s put you front and center. Say this:

Two new APIs enable you to work with temporary files….

Further, don’t say this:

when uploading a managed file

Say this:

when you upload a managed file

Finally, don’t say this:

prior to creating or updating

Say this:

before you create or update

Latin Phrases

Latin phrases are fine in most work organizations. I don’t allow them in my work organization documentation because many of my authors don’t seem to know the true meanings of i.e., e.g., via, and etc., and I am tired of correcting my authors. Just stick to American English and you will never go wrong.

Sic transit gloria mundi.

Usage

The phrase prior to has the musty smell of the law office. Use before.

Simple Sentences

See the Revision section for a good way to divide the sentence into two sentences.

Parentheses

The example sentence talks about how temporary files are created and why they are important. This is NOT trivial information, as you might find in an aside or an offhand comment. DO NOT put important information in parentheses. If it is important, it deserves to be on equal footing with the other sentences.

As an ordinary reader, I find too much material enclosed in parentheses to be an annoying mannerism. Parentheses break up the natural flow of a sentence or sentences.

To make my point—when was the last time you read an exciting, page-turner novel that used an excessive amount of parentheses? Good authors avoid them.

REVISION

Before

Two new APIs are available for working with temporary files (i.e., the files created when uploading a managed file prior to creating or updating the associated content object).

After

Two new APIs enable you to work with temporary files. You create the temporary files when you upload a managed file before you create or update the associated content object.

You create temporary files when you upload a managed file before you create or update the associated content object. Two new APIs enable you to work with these temporary files.

Example 21

REWRITE THIS SENTENCE

PROBLEM

This meandering sentence is in serious need of an overhaul. I propose to do two things:

Divide it into at least two sentences.
Make everything active voice.

DISCUSSION

Active Voice

Who or what is the main actor in the sentence? Who or what sets the language?

The actor is the geolocation feature, which is near the end of the sentence next to the caboose. Start the sentence with the geolocation feature. Say this:

The geolocation feature determines the language in which the notification email is sent.

How does the geolocation feature do this? It uses the IP address to identify the country. By identifying the country, it identifies the appropriate language.

Simple Sentences

The example sentence expresses three thoughts. This means you can have three short, logically-sequenced sentences replace one long rambling sentence:

The geolocation feature determines the language in which the notification email is sent.
It uses the IP address to identify the country.
By identifying the country, it identifies the appropriate language.

REVISION

Before

The language that notification emails use is set by the country determined by the geolocation feature, which maps a country to a guest’s IP address.

After

The geolocation feature determines the language in which the notification email is sent. It uses the IP address to identify the country. By identifying the country, it identifies the appropriate language.

Example 22

REWRITE THIS SENTENCE

PROBLEM

Passive voice. Fix it.

DISCUSSION

Who or what is doing the testing? We are. Don’t be shy about it.

Say this:

During the summer of 2015, we completed the required testing….

REVISION

Before

During the summer of 2015, required testing was completed in order to certify Microsoft SQL Server 2014 for use with FakeCorp CMS 8.1.

After

During the summer of 2015, we completed the required testing in order to certify Microsoft SQL Server 2014 for use with FakeCorp CMS 8.1.

Example 23

How Texas Teaches History

By Ellen Bresmore Rockwell, Dartmouth College

Reprinted from the New York Times Opinion section, October 21, 2015

A TEXAS high school student and his mother recently called attention to a curious line in a geography textbook: a description of the Atlantic slave trade as bringing “millions of workers” to plantations in the American South. McGraw-Hill Education, the publisher of the textbook, has since acknowledged that the term “workers” was a misnomer.

The company’s chief executive also promised to revise the textbook so that its digital version as well as its next edition would more accurately describe the forced migration and enslavement of Africans. In the meantime, the company is also offering to send stickers to cover the passage.

But it will take more than that to fix the way slavery is taught in Texas textbooks. In 2010, the Texas Board of Education approved a social studies curriculum that promotes capitalism and Republican political philosophies. The curriculum guidelines prompted many concerns, including that new textbooks would downplay slavery as the cause of the Civil War.

This fall, five million public school students in Texas began using the textbooks based on the new guidelines. And some of these books distort history not through word choices but through a tool we often think of as apolitical: grammar.

In September, Bobby Finger of the website Jezebel obtained and published some excerpts from the new books, showing much of what is objectionable about their content. The books play down the horror of slavery and even seem to claim that it had an upside. This upside took the form of a distinctive African-American culture, in which family was central, Christianity provided “hope,” folk tales expressed “joy” and community dances were important social events.

But it is not only the substance of the passages that is a problem. It is also their form. The writers’ decisions about how to construct sentences, about what the subject of the sentence will be, about whether the verb will be active or passive, shape the message that slavery was not all that bad.

I teach freshman writing at Dartmouth College. My colleagues and I consistently try to convey to our students the importance of clear writing. Among the guiding principles of clear writing are these: Whenever possible, use human subjects, not abstract nouns; use active verbs, not passive. We don’t want our students to write, “Torture was used,” because that sentence obscures who was torturing whom.

In the excerpts published by Jezebel, the Texas textbooks employ all the principles of good, strong, clear writing when talking about the “upside” of slavery. But when writing about the brutality of slavery, the writers use all the tricks of obfuscation. You can see all this at play in the following passage from a textbook, published by Houghton Mifflin Harcourt, called Texas United States History:

Some slaves reported that their masters treated them kindly. To protect their investment, some slaveholders provided adequate food and clothing for their slaves. However, severe treatment was very common. Whippings, brandings, and even worse torture were all part of American slavery.

Notice how in the first two sentences, the “slavery wasn’t that bad” sentences, the main subject of each clause is a person: slaves, masters, slaveholders. What those people, especially the slave owners, are doing is clear: They are treating their slaves kindly; they are providing adequate food and clothing. But after those two sentences there is a change, not just in the writers’ outlook on slavery but also in their sentence construction. There are no people in the last two sentences, only nouns. Yes, there is severe treatment, whippings, brandings and torture. And yes, those are all bad things. But where are the slave owners who were actually doing the whipping and branding and torturing? And where are the slaves who were whipped, branded and tortured? They are nowhere to be found in the sentence.

In another passage, slave owners and their institutionalized cruelty are similarly absent: “Families were often broken apart when a family member was sold to another owner.”

Note the use of the passive voice in the verbs “were broken apart” and “was sold.” If the sentence had been written according to the principles of good draftsmanship, it would have looked like this: Slave owners often broke slave families apart by selling a family member to another owner. A bit more powerful, no? Through grammatical manipulation, the textbook authors obscure the role of slave owners in the institution of slavery.

It may appear at first glance that the authors do a better job of focusing on the actions of slaves. After all, there are many sentences in which “slaves” are the subjects, the main characters in their own narrative. But what are the verbs in those sentences? Are the slaves suffering? No, in the sentences that feature slaves as the subject, as the main actors in the sentence, the slaves are contributing their agricultural knowledge to the growing Southern economy; they are singing songs and telling folk tales; they are expressing themselves through art and dance.

There are no sentences, in these excerpts, anyway, in which slaves are doing what slaves actually did: toiling relentlessly, without remuneration or reprieve, constantly subject to confinement, corporal punishment and death.

The textbook publishers were put in a difficult position. They had to teach history to Texas’ children without challenging conservative political views that are at odds with history. In doing so, they made many grammatical choices. Though we don’t always recognize it, grammatical choices can be moral choices, and these publishers made the wrong ones.

Ellen Bresler Rockmore is a lecturer in the Institute for Writing and Rhetoric at Dartmouth.