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

Example 1

REWRITE THIS SENTENCE

PROBLEM

Passive voice
Awkward word order
Usage of the word invoke (is this really a problem?)

DISCUSSION

Passive Voice

Who or what provides the several functions to invoke the FakeApp? Since I plucked this sentence out of its broader context, I will tell you. The new application provides the functions.

Now that you know who is doing the providing, let’s rearrange the sentence as active voice with application as the actor.

Word Order

The word order of this sentence is awkward from beginning to end. After you make the first part of the sentence active voice, you might consider a second sentence in which you call out the login page as an example.

Invoke

The word invoke has a specific meaning in software documentation. From Webopedia:

To activate. One usually speaks of invoking a function or routine in a program. In this sense, the term invoke is synonymous with the word call.

Invoke is seldom used in ordinary speech and writing, but is a commonly understood term in the software industry. It is OK to use it.

REVISION

Before

Several functions have been provided for invoking the FakeApp on certain pages, such as opening the login page.

After

The application enables you to use several different functions to invoke the FakeApp on certain pages. For example, there is more than one way to open the login page.

You can use several different functions to invoke the FakeApp on certain pages. For example, there is more than one way to open the login page.

NOTE: The second rewrite uses the you Can Do Something construction. In this case, its usage is acceptable because you are describing something where you truly have several options. It is not a direct command to perform an act in one specific manner.

Example 2

REWRITE THESE SENTENCES

PROBLEM

In the first sentence, the verb form can subscribe to is split by the adverb optionally.

In the second sentence, the verb form is logged in is split by the adverb currently.

DISCUSSION

Good technical writing requires two things: (a) it must be technically accurate and (b) it must be readable. While splitting the verb form is OK grammatically and is done all the time, split verb forms do not, in my opinion, enhance readability. If anything, splitting the verb form tends to slow the reader down because the reader has to put the first part of the verb form into a hold pattern as he or she processes the word doing the splitting.

Unless you have a compelling reason to split the verb form, my advice is to put the would-be splitting word either before or after the verb form.

One compelling reason to split the verb form is to make an emphatic point. For example, take this sentence:

The results are posted automatically now.

Suppose, up to this point, the user had to post the results manually. With this new release, however, the user does not have to bother with that any more. Now the system posts the results automatically. That is a good thing, right? You can make the happy announcement this way:

The results are automatically posted now.

You make the emphatic point precisely because the verb form is split. Typically, verb forms are intact. The very act of splitting the verb form grabs the reader’s attention.

To summarize: Don’t split the verb form unless you are looking for some shock value. If you aren’t looking for shock value and you split verb forms over and over again, you are making the reader’s job more difficult.

Making the Case for the Passive Voice

Did you notice our example sentence is in the passive voice? English teachers and technical editors are seldom kind to the passive voice. But sometimes the passive voice is the best way to say something.

Here is our sentence:

The results are automatically posted now.

OK, who is the actor? It is not the user; it is the system or some other term for the system. You could say this:

The system automatically posts the results now.

That sounds a little awkward. It sounds awkward because no one really cares about the system. We care most about the user’s good fortune now that the results are posted automatically.

I am making this point to show you that making every sentence active voice is not always the best solution. Occasionally, the passive voice works just as well or even better.

REVISIONS

Before

The user can optionally subscribe to some FakeCorp newsletters.

The GuestCheck method determines if the guest is currently logged in.

After

As an option, the user can subscribe to some FakeCorp newsletters.

The GuestCheck method determines if the guest is logged in currently.

Example 3

REWRITE THIS SENTENCE

PROBLEM

The verb in this sentence is to log in. The word automatically is an adverb. Generally, the grammar rule is this: Do not insert an adverb in the middle of a verb form unless you want to draw special attention to the adverb. As it happens in the context of our example sentence, the sentence is simply passing along routine information to the reader. In other words, the author is not trying to stress the automatic nature of the operation.

Having said this, how should you rewrite the sentence?

DISCUSSION

Don’t split the verb form unless you are looking for some shock value.

REVISION

Before

The teen or adult user completes a registration on a site and is automatically logged in.

After

The teen or adult user completes a registration on a site and is logged in automatically.

Example 4

REWRITE THIS SENTENCE

PROBLEM

The sentence begins well, but it ends with two dependent clauses, one after the other. The word order is awkward.

These are the dependent clauses:

as opposed to a web-based service or shell
which requires you to be on-line

DISCUSSION

You need to do two things:

Divide the sentence into two sentences
Find a more direct and assertive word order

REVISION

Before

When you use a POP client to connect and download your email, you do not have to be online to read and reply to your mail, as opposed to a web-based service or shell, which requires you to be on-line.

After

When you use a POP client to connect and download your email, you do not have to be online to read and reply to your mail. This is different from a web-based service or shell, which requires you to be online.

Or better

You do not have to be online to read and reply to your mail when you use a POP client to connect and download your email. This is different from a web-based service or shell, which requires you to be online.

Example 5

REWRITE THIS SENTENCE

PROBLEM

The example sentence has four problems:

Can Do Something
Passive Voice
Word Order
Wordiness

DISCUSSION

Can Do Something

Skip the Can Do Something construction. Go directly to the action verb. The action verb is not to perform. See the following section on Wordiness for the true action verb.

Passive Voice

Always write in the active voice, if possible. See the revised sentence.

Word Order

Start the sentence with the action verb and the tool, this API.

Wordiness

The true action verb for this sentence is to manage.

Instead of saying:

The management of permissions can be performed

Say this:

manage the permissions

See the revised sentence.

REVISION

Before

The management of permissions can be performed using this API.

After

Use this API to manage the permissions.

Example 6

REWRITE THIS PARAGRAPH

PROBLEM

The example sentences suffer from these defects:

Passive voice
Perfect tense—use the present tense instead
Two sentences contain four distinct thoughts—rewrite as four simple sentences
Awkward word order

DISCUSSION

Passive Voice

This phrase:

that have been found

Found by whom or what?

Perfect Tenses

Again, this phrase:

that have been found

Use the present tense.

Simple Sentences

See the rewrite.

Word Order

This sentence in particular has awkward word order:

Outgoing responses from the user controller may contain errors that have been found while processing the request that need to be reported back to the caller.

See the rewrite.

REVISION

Before

Outgoing responses from the user controller may contain errors that have been found while processing the request that need to be reported back to the caller. The following details how error handling happens by looking at an example request flow.

After

Outgoing responses from the user controller may contain errors that occur while the system processes the request. These errors are reported back to the caller. The following information explains how error handling occurs. We will examine an example request flow.

Example 7

REWRITE THIS SENTENCE

PROBLEM

The word potentially.

DISCUSSION

The sentence has an awkward sound because of the placement of the word potentially. It is best to set potentially at the beginning of the sentence so there is no doubt about the meaning. Make sure you add a comma before moving on to the rest of the sentence.

REVISION

Before

Most creatives are stored potentially in a template with other equivalent creatives.

After

Potentially, most creatives are stored in a template with other equivalent creatives.

Example 8

REWRITE THIS SENTENCE

PROBLEM

This is an awkward conditional statement. In fact, there are three conditions:

Event-based emails
A direct HTTP call
Any errors or issues connecting to Blitz (Note that Blitz—not its real name—is a software tool.)

The author does a poor job of laying out the conditional scenario. At the very least, the word order needs improvement.

In addition, the example sentence also suffers from these issues:

Comma fault, after cases and before otherwise
Run-on sentence—we need to break the sentence into two or more sentences
Future tense; present tense is preferred

DISCUSSION

Conditional Statements

Instead of saying this:

For event-based emails, when using a direct HTTP call, if there are any errors or issues connecting to Blitz, the template needs to handle those cases….

Say this:

When you use a direct HTTP call for your event-based email, and you have errors or issues connecting to Blitz, you need to use the template.

Comma Fault and Run-on Sentence

These two problems are connected. Start a new sentence after you mention the template.

Future Tense vs. Present Tense

Don’t say this:

…otherwise User Services’ Titanic system handles this and will automatically retry….

Say this:

Otherwise, User Services’ Titanic system handles this, and automatically retries….

REVISION

Before

For event-based emails, when using a direct HTTP call, if there are any errors or issues connecting to Blitz, the template needs to handle those cases, otherwise User Services’ Titanic system handles this and will automatically retry in case there is a failure to connect.

After

When you use a direct HTTP call for your event-based email, and you have errors or issues connecting to Blitz, you need to use the template. Otherwise, User Services’ Titanic system handles this, and automatically retries in case there is a failure to connect.

Example 9

REWRITE THESE SENTENCES

PROBLEM

In both sentences, the author placed an adverb in the middle of a verb form. My recommendation is to avoid this practice unless you want to use the adverb for emphasis.

On the web page from which I found these two example sentences, clearly the author did not mean to emphasize manual publishing or unpublishing or the automatic validation of the schedule. These are simply routine outcomes of a routine process.

DISCUSSION

You enhance readability when you keep the verb form intact. Don’t split the verb form unless you want to make an emphatic point.

As an example of extraordinary vs. routine, take these two sentences:

You must use the update content API to move the content manually to its new section.

You must use the update content API to manually move the content to its new section.

The first sentence describes a routine operation. The second sentence stresses this is a manual operation, which is not routine.

REVISION

Before

You can manually publish or unpublish the current default draft from any content grid or from the draft manager.

The draft publishing schedule is automatically validated.

After

You can publish or unpublish the current default draft manually from any content grid or from the draft manager.

The draft publishing schedule is validated automatically.

Example 10

REWRITE THIS SENTENCE

PROBLEM

Two problems:

Passive voice
Word order

DISCUSSION

The sentences begins with a dependent clause (For each environment in which a DCS is used), and then moves into an independent clause (the DCS host or hosts must be specified using one of the following methods). Both clauses are in the passive voice. Change each clause to the active voice. See the Revision section for the rewrite.

Also, the independent clause is a procedure. You need to rearrange the wording so it appears like a step. When you write a step, the first thing you should do is tell the user or reader where to start. Tell the user/reader to (a) go to the location on the user interface or (b) identify the tool to use. In this case, we are identifying the tool—one of the following methods. Start with that.

Don’t say this:

the DCS host or hosts must be specified using one of the following methods

Say this:

use one of the following methods to specify the DCS host or hosts

REVISION

Before

For each environment in which a DCS is used, the DCS host or hosts must be specified using one of the following methods.

After

For each environment in which you use a DCS, use one of the following methods to specify the DCS host or hosts.

Example 11

REWRITE THIS SENTENCE

PROBLEM

Fix these problems:

Latin phrases (use English words)
Passive voice
Usage (the word impacted)
Word order (rearrange the wording after the coordinating conjunction and)

DISCUSSION

Latin Phrases

Don’t say this:

…and the feature can’t be toggled conventionally via the site editor or the CMS API.

Say this:

…and you can’t use the site editor or the CMS API to toggle it conventionally

Passive Voice

Don’t say this:

…and the feature can’t be toggled conventionally via the site editor or the CMS API.

Who or what is doing the toggling?

Say this:

…and you can’t use the site editor or the CMS API to toggle it conventionally

Usage

My preference is to use the word affected instead of the word impacted. Impact makes me think of a large crater.

Word Order

The awkward word order of our sentence is a function of the passive voice construction. This is a good example of how passive voice sentence construction and awkward word order often are intimately connected.

When we sail into the second half of the sentence, after the conjunction and, start the second independent clause by calling out these two tools first:

site editor
CMS API

See the Revision section for the rewrite.

REVISION

Before

The livelisteners.disabled property key is a manual override to turn off the live listener feature if CMS startup is impacted and the feature can’t be toggled conventionally via the site editor or the CMS API.

After

The livelisteners.disabled property key is a manual override used to turn off the live listener feature if CMS startup is affected and you can’t use the site editor or the CMS API to toggle it conventionally.

Example 12

REWRITE THIS PARAGRAPH

PROBLEM

Two problems:

Passive voice in the first sentence
Awkward word order in the second sentence

DISCUSSION

Passive Voice

Don’t say this:

All APIs … are available through the FakeCorp API documentation

Say this:

The FakeCorp API documentation contains all APIs….

Word Order

These are instructions to your reader. Put your reader at the center of the action. Start the sentence with the second person singular, You. Say this:

You must have an appropriate AuthenticationPlus token for access to this documentation.

REVISION

Before

All APIs, including supported input and output, and lists of error codes and their meanings for each endpoint, are available through the FakeCorp API documentation. Access to this documentation requires an appropriate AuthenticationPlus token.

After

The FakeCorp API documentation contains all APIs, including supported input and output, and lists of error codes and their meanings for each endpoint. You must have an appropriate AuthenticationPlus token for access to this documentation.

Example 13

REWRITE THIS SENTENCE

PROBLEM

Word order: The author split the verb form are known with the word colloquially.

DISCUSSION

When you want to emphasize something highly unusual, it is OK to split the verb form. Verb forms naturally belong together. In this example sentence, the verb form is to know. Splitting the verb form draws the reader’s attention to something out of the ordinary. However, in this sentence, the author is simply making a statement of fact.

Here is a different example. Take these two versions of the same sentence where the verb form is are posted:

The results are automatically posted now.

The results are posted now automatically.

The first sentence, are automatically posted now, indicates something new and different. The emphasis is on automatically. You might find this kind of statement in release notes. Perhaps the user had to post the results manually in the past. However, with this new release, the system now posts the results automatically.

The second sentence, are posted now automatically, is an undramatic statement about how the user gets the results.

REVISION

Before

These configurations are colloquially known as the client config.

After

These configurations are known colloquially as the client config.

Example 14

REWRITE THIS SENTENCE THAT INTRODUCES A LIST

PROBLEM

Fix these problems:

Latin phrases
Passive voice
Usage
Word order

DISCUSSION

Latin Phrases

Don’t say this:

via

See the following Word Order section in this post for a way to avoid using a Latin phrase.

Passive Voice

Don’t say this:

…the following common fields may be requested…

Say this:

…get the following common fields

Usage

Don’t say this:

requested

Say this:

get

Word Order

When you give instructions to the user, specify the tool to use first. In this case, tell the user to Use the API [to do something].

Say this:

Use this API to get the following common fields.

REVISION

Before

The following common fields may be requested via this API:

After

Use this API to get the following common fields.

Example 15

REWRITE THIS SENTENCE

PROBLEM

Fix these issues:

Misuse of Latin phrases
Using the future tense when the present tense is more direct and immediate
Using which instead of that
Writing a sentence with awkward word order

DISCUSSION

Latin Phrases

First of all, never use e.g. and etc. in the same context. It’s bad form. When translated to our language—American English—this is how it sounds:

…(for example, content, content type, template processor, and so on)….

Use for example or and so on, but not both together. It is a redundancy.

I prefer American English in all forms of technical writing, but I go along with Latin phrases if my authors truly know how to use them appropriately.

Present Tense vs. Future Tense

The CMS object causes referenced objects to be implicitly included for migration both in the future and right now. Since it is both, use the present tense rather than the future tense.

Which vs. That

For a good explanation of the difference between which and that, go to Quick and Dirty Tips by Mignon Fogarty, the Grammar Girl.

Word Order

Don’t say this:

…which has been explicitly specified for migration will cause any referenced objects to be implicitly included for migration.

Say this:

…that is specified explicitly for migration implicitly causes any referenced objects to be included for migration.

In our example sentence, the words explicitly and implicitly are inserted in the middle of the verb forms. Don’t split verb forms unless you intend to startle your reader with some shocking news. That is not the case with the example sentence. We are simply passing along routine information here.

In my rewrite, I put explicitly after the verb form and the word implicitly before the verb form. Thus, the verb forms remain intact.

REVISION

Before

A CMS object (e.g., content, content type, template processor, etc.) which has been explicitly specified for migration will cause any referenced objects to be implicitly included for migration.

After

A CMS object (for example, content, content type, and template processor) that is specified explicitly for migration implicitly causes any referenced objects to be included for migration.