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

Example 1

REWRITE THESE SENTENCES

PROBLEM

kick off or kickoff?
back up or backup?
set up or setup?
log in or login?
log out or logout?

All of the example sentences are incorrect.

DISCUSSION

Verb

When used as a verb, it is always two words:

to kick off
to back up
to set up
to log in
to log out

Noun

When used as a noun, it is always one word:

The kickoff for the Seahawks game is Sunday at 1:25 PM.
I saved a backup of the file.
What is the setup for the conference call?
What is the password for the wi-fi login?
Click Logout.

Modifier

When used as a modifier, or adjective, it is always one word.

We have a kickoff meeting at 9:00 AM.
The backup file is in this folder.
For the setup instructions, click Start.
Make sure you have a strong login password.
Are you ready to review the logout procedure?

REVISION

1 (verb)

Before

Contact Customer Service to kickoff your upgrade plan.

After

Contact Customer Service to kick off your upgrade plan.

2 (noun)

Before

When is the kick off?

After

When is the kickoff?

3 (modifier)

Before

When is the kick off meeting?

After

When is the kickoff meeting?

4 (noun)

Before

Make a back up of the CMS database.

After

Make a backup of the CMS database.

5 (verb)

Before

Make sure you backup your files.

After

Make sure you back up your files.

6 (verb)

Before

Now that you have everything setup and provisioned, let’s run through a quick sample to get you started.

After

Now that you have everything set up and provisioned, let’s run through a quick sample to get you started.

7 (noun)

Before

Now that you’re done with the set up, what’s next?

After

Now that you’re done with the setup, what’s next?

8 (modifier)

Before

Check the FAQ page to see if others have had the same issues, or set up quirks.

After

Check the FAQ page to see if others have had the same issues, or setup quirks.

9 (verb)

Before

If the user is not logged in, this prompts the user to login.

After

If the user is not logged in, this prompts the user to log in.

10 (noun)

Before

You can launch account recovery from the main FakeApp Log In UI.

After

You can launch account recovery from the main FakeApp Login UI.

11 (verb)

Before

A guest can choose to logout by clicking the Logout button on the FakeCorp website.

After

A guest can choose to log out by clicking the Logout button on the FakeCorp website.

Example 2

REWRITE THESE SENTENCES

PROBLEM

Today’s lesson in readability: Don’t utilize big words.

DISCUSSION

The verb form to utilize and the verb form to use mean the same thing. In most cases, the monosyllabic word use is an acceptable substitute for the verb utilize.

Years ago when I was working at the Boeing Company, I suggested to an engineer that he use use instead of utilize. I asked him why use a 50 cent word when a nickel word worked just as well. He agreed the meaning was the same, but he said he felt like he was working harder when he utilized something. That is the best defense I ever heard for utilize and its pretentious cousin utilization.

CAUTION: Engineers of all stripes love the word utilization. It often appears in formal software nomenclature. Don’t ever change the word if it is part of an official name of a product or process.

REVISIONS

Before

Utilize a database for distribution lists.

After

Use a database for distribution lists.

Before

It utilizes the FakeApp lists and user data to fine tune marketing lists used by AnotherFakeApp.

After

It uses the FakeApp lists and user data to fine tune marketing lists used by AnotherFakeApp.

Before

This list or portions of it are utilized for filter of targeted mails to ensure exclusion of guests and users who previously submitted a suppression request.

After

This list or portions of it are used for filter of targeted mails to ensure exclusion of guests and users who previously submitted a suppression request.

Example 3

REWRITE THESE SENTENCES USING ENGLISH WORDS

PROBLEM

Each sentence contains a Latin phrase. In each case, the Latin phrase is used correctly. The problem is some authors use Latin phrases, but they don’t know the exact meaning of the phrases they use.

DISCUSSION

Here are the definitions:

e.g. comes from the Latin phrase exempli gratia, which means for the sake of example. Use for example.
i.e. comes from id est. It means that is. Use that is.
etc. or et cetera, means and other things, and so forth, and the rest. Use and so on.
via literally means by way of. Use by using or through.

Check your organization’s style sheet to see if it is OK to use Latin phrases. If it is not OK, use the English phrases on this page.

If Latin phrases are OK, make sure you use them correctly. For example, never use e.g. at the beginning of a phrase and etc. at the end of the phrase. Either begin with for example or end with and so on. Don’t do both.

I don’t encourage the use of Latin phrases. My preference is to not use them at all. I give your three reasons. First, we live in America and American English is our language. Second, Latin phrases convey the self-important tone of legal documentation. Finally, Latin phrases may cause localization problems as your documentation is translated into other languages.

On this last point: It is a problem especially when the author uses the Latin phrase incorrectly and the technical editor does not catch it!

REVISIONS

Before

This resource defines the feature type (i.e., Boolean, String, Int, and enumerated types).

This enables the guest to update his or her information via the UI.

If the validation filter throws an exception (e.g., the user gave an invalid token or an expired token), the system returns a 401 Unauthorized message.

For ISP blocks (WarmMail, FutureOfAwesome, etc.), typically the incidents trigger an alert.

After

This resource defines the feature type (that is, Boolean, String, Int, and enumerated types).

This enables the guest to update his or her information through the UI.

This enables the guest to update his or her information by using the UI.

If the validation filter throws an exception (for example, the user gave an invalid token or an expired token), the system returns a 401 Unauthorized message.

For ISP blocks (WarmMail, FutureOfAwesome, and so on), typically the incidents trigger an alert.

Example 4

REWRITE THESE SENTENCES

PROBLEM

The word please.

DISCUSSION

Use this word sparingly. Never use it in a procedural sentence where the specified action is mandatory. Please can be interpreted to mean that a required action is optional. Also, if you use it too often, you strike an obsequious tone.

REVISIONS

Before

Please see the app controller documentation for more information.

If you use the Apache HTTP client (Java) to call AuthenticationPlus, please note that Apache HTTP client connection pooling is not always reliable when you make that call.

If your requirements are not satisfied by the reference implementation, please use the following code.

To connect to services running in the WXYZ managed hosting environment, please become familiar with this policy and its implications on connectivity.

After

See the app controller documentation for more information.

If you use the Apache HTTP client (Java) to call AuthenticationPlus, note that Apache HTTP client connection pooling is not always reliable when you make that call.

If your requirements are not satisfied by the reference implementation, use the following code.

To connect to services running in the WXYZ managed hosting environment, become familiar with this policy and its implications on connectivity.

Example 5

REWRITE THESE SENTENCES

PROBLEM

The words runtime and run time.

DISCUSSION

Run time is the time during which an application is running, as in at run time. Think chronological time for run time.

A runtime is an environment that is required to run programs that are not compiled to machine language. Think a specified software environment for runtime.

REVISIONS

Before

As an option, you can choose a background image at runtime.

In computer science, run time, or execution time is the time during which a program is running (executing), in contrast to other phases of a program’s life cycle such as compile time, link time, load time, and so on.

After

As an option, you can choose a background image at run time.

In computer science, runtime, or execution time is the time during which a program is running (executing), in contrast to other phases of a program’s life cycle such as compile time, link time, load time, and so on.

Example 6

REWRITE THESE SENTENCES

PROBLEM

There is a subtle difference between the preposition in and the preposition within. Here are the definitions:

In—In is a preposition that denotes inclusion or location. It can also mean “into.”
Within—Within has a meaning of “inside the boundaries or limits.” Most often, usage of within in software documentation has to do with time restrictions.

DISCUSSION

Let’s look at our example sentences one by one.

Track individual links within the message body.

This takes the word in because it speaks to a location, in the message body.

The user must create the full account in the specified time to live after becoming a new prospect.

The word within is defined as “inside the boundaries or limits.” The sentence mentions a specific time to live, or TTL. The user must create a full account within the boundaries of the TTL. Therefore, within is correct.

To learn how to launch the login screen within your application, see the User Login page.

There are no boundaries or limits here. That is, there are no restrictions from beginning to end. We are talking about a specific location on the user interface. The User Login page is included as part of the UI. The word in is correct.

REVISIONS

Before

Track individual links within the message body.

The user must create the full account in the specified time-to-live after becoming a new prospect.

To learn how to launch the login screen within your application, see the User Login page.

After

Track individual links in the message body.

The user must create the full account within the specified time-to-live after becoming a new prospect.

To learn how to launch the login screen in your application, see the User Login page.

Example 7

REWRITE THESE SENTENCES

PROBLEM

The words dialog and d-box.

DISCUSSION

In software documentation, never use dialog or dialogs for dialog box or dialog boxes. Never use the abbreviation d-box.

REVISIONS

Before

Click OK to close the dialog.

Double-click on the appropriate connection to open the Properties d-box.

After

Click OK to close the dialog box.

Double-click on the appropriate connection to open the Properties dialog box.

Example 8

CONVERT THE FOLLOWING LATIN PHRASES TO ENGLISH WORDS

PROBLEM

These four Latin phrases are used all the time in technical writing:

e.g.
i.e.
etc.
via

If your organization’s style guide allows you to use these Latin phrases, you should—at the very least—know what they mean. If your style guide does not allow you to use Latin phrases, you need to replace the Latin phrases with the correct English words.

DISCUSSION

Here are the definitions:

e.g. comes from the Latin phrase exempli gratia, which means for the sake of example. Use for example.
i.e. comes from id est. It means that is. Use that is.
etc. or et cetera, means and other things, and so forth, and the rest. Use and so on.
via literally means by way of. Use by using or through.

This is what I said in a previous essay:

Check your organization’s style sheet to see if it is OK to use Latin phrases. If it is not OK, use the English phrases on this page.

If Latin phrases are OK, make sure you use them correctly. For example, never use e.g. at the beginning of a phrase and etc. at the end of the phrase. Either begin with for example or end with and so on. Don’t do both.

On this last point: It is a problem especially when the author uses the Latin phrase incorrectly and the technical editor does not catch it!

REVISION

Before

I went to my least favorite place (i.e., the dentist).

The buffet provided excellent variety, e.g., vegetarian and non-vegetarian soups, Italian and French breads, and numerous sweets.

Green vegetables (broccoli, spinach, etc.) can be good for your health.

Send the message via our own SMTP server.

After

I went to my least favorite place (that is, the dentist).

The buffet provided excellent variety, for example, vegetarian and non-vegetarian soups, Italian and French breads, and numerous sweets.

Green vegetables (broccoli, spinach, and so on) can be good for your health.

Send the message through our own SMTP server.

Send the message by using our own SMTP server.

Example 9

WHICH SENTENCE IS CORRECT?

PROBLEM

I am opening up the and/or can of worms.

Let’s assume you think it is OK to use and/or in a sentence. Which sentence is correct?

On the other hand, if you do not think and/or is OK:

Why is it not OK?
What is your preferred revision?

DISCUSSION

If you think and/or is OK, this is the correct answer:

The subject of a sentence generally is defined as the noun or pronoun engaging in the activity of the verb. When a sentence has two or more subjects, we call it a compound subject.

RULE: When the subjects are joined by and, or, and/or, or neither/nor, the verb agrees with the subject that is closest to the verb.

The verb are is closest to the subject attachments. Therefore, use the plural form are.

My Opinion

I do not like and/or for several reasons. The main reason is readability. It makes the reader pause because, initially, it is not clear what the author is talking about. Of course, after the reader takes the extra time to re-read the sentence two or three times, it might make sense. But because of the author’s cute grammatical construction, the author has unnecessarily wasted some of the reader’s valuable time.

In addition, and/or lacks precision. Technical writing is supposed to be precise and accurate. Here is an example of a confusing and/or construction:

x and/or y

contrasting to this better rewrite:

x or y or both

You run into major problems when you use and/or for three or more items. For example, take this sentence:

He will eat either cake, pie, and/or brownies.

The and/or construction introduces a gratuitously confusing picture for the reader. The and/or brownies part of the sentence is the problem.

Does it mean this?

He will eat either cake, pie, or brownies. (one of the three—although it reads better when you remove the word either in this sentence and in all of the following sentences)

Or this:

He will eat either cake, pie, and brownies. (all of them—also, the word either is misused because it does not go with and)

Or this:

He will eat either cake and brownies. (exclude pie—also, the word either is misused because it does not go with and)

Or this:

He will eat either pie and brownies. (exclude cake—also, the word either is misused because it does not go with and)

IMPORTANT: Never use the and/or construction for three or more items. If you must use and/or, make sure it is a choice between just two items.

REVISIONS

Before

This message and/or attachments is confidential.

This message or attachments are confidential.

After

This message or its attachments or both are confidential.

Example 10

REWRITE THIS SENTENCE

PROBLEM

The phrase whether or not.

DISCUSSION

If you take the words or not out of the phrase whether or not, the meaning of the sentence is exactly the same, and you make the sentence more concise.

REVISION

Before

You have the option whether or not to use the external URI base in the rewritten URIs.

After

You have the option whether to use the external URI base in the rewritten URIs.

Example 11

REWRITE THESE SENTENCES

PROBLEM

Ah, the age-old question whether to use the word affect or effect. Does that ever puzzle you?

DISCUSSION

Let’s keep this simple.

The website called Vocabulary has a memorable explanation. Whenever you can’t decide between affect and effect, I want you to think of this poet:

And this dirty old bird:

Your mental gimmick is RAVEN. RAVEN stands for this:

R – Remember

A – Affect

V – Verb

E – Effect

N – Noun

Sentence 1

FakeCorp is committed to resolving issues that effect the performance and availability of the service.

The word should be affect because it is a verb (that is, to affect).

Sentence 2

What is the affect on resolution time?

The word should be effect because it is a noun.

Exceptions to the RAVEN Rule

Sometimes effect is used as a verb. From Vocabulary:

Adding to the confusion, effect can also be used as a verb to mean to produce or to cause to come into being. Here’s an example that uses it correctly: “A government unable to effect any change is a government that will produce no surprises.” Put another way, a government that can’t produce change won’t be able to produce surprises; it will be predictable.

Got it? Good.

REVISIONS

Before

FakeCorp is committed to resolving issues that effect the performance and availability of the service.

What is the affect on resolution time?

After

FakeCorp is committed to resolving issues that affect the performance and availability of the service.

What is the effect on resolution time?

Example 12

REWRITE THIS SENTENCE

PROBLEM

The word within is misused. Use the word in.

DISCUSSION

The word in is a preposition that indicates inclusion or location. It also means into.

The word within is also a preposition that means inside the boundaries or limits. In other words, it means the space—either physically or metaphorically—between point a and point b.

In our example sentence, there is no indication the error occurred inside any boundaries or limits. The error is found in the admin controller service—a specific location. Therefore, in is the correct usage.

REVISION

Before

An error occurred within the admin controller service.

After

An error occurred in the admin controller service.

Example 13

REWRITE THIS SENTENCE

PROBLEM

The phrase

and not get what you want

Refers back to

you saw us go all the way

The second-person singular you refers back to the third-person plural us.

DISCUSSION

This verbal error happens all too frequently, especially in speech. When it comes to pronoun reference, you must be consistent from beginning to end.

REVISION

Before

You saw us win it all, and you saw us go all the way to the last moment and not get what you want.

After

You saw us win it all, and you saw us go all the way to the last moment and not get what we want.

Example 14

FIX THE PROBLEMS IN THIS LIST

PROBLEM

This brief list has many problems. Here is a summary:

Latin Phrases
- via
Passive Voice
Punctuation
- Consistency of end punctuation
Spelling
- Recipients
- receive
- Recipients
Usage
- wish vs. want
- that vs. who
- receive vs. get

DISCUSSION

Latin Phrases

Instead of via, say by using or through.

Passive Voice

Instead of saying:

Recipient lists can be created

Say this:

You can create recipient lists

Punctuation

One of the three bullet items (that is, the second bullet item) has end punctuation. In a bullet list, punctuate all the bullet items or none of the bullet items. You must be consistent.

Spelling

Make these changes:

Change Recipents to Recipients
Change recieve to receive
Change Reciptents to Recipients

Usage

Use the word want instead of wish. Wishing for something is like hoping you will get it; want is more direct. Also, want is better for localization.

The phrase Recipients that is incorrect. Recipients are persons. Therefore, use the word who instead of that.

While the word receive is acceptable usage, you might consider using the one-syllable verb get. It means the same thing.

REVISION

Before

Recipient lists can be created via many different mechanisms and for different purposes such as:

- Recipents that wish to recieve a message every time the Seahawks score a touchdown
- Recipents that are targets of a marketing campaign assembled in Unica or some other tool.
- Reciptents that wish to recieve results of running a query against a database

After

You can create recipient lists by using many different mechanisms and for different purposes such as:

- Recipients who want to get a message every time the Seahawks score a touchdown
- Recipients who are targets of a marketing campaign assembled in Unica or some other tool
- Recipients who want to get results of running a query against a database

Example 15

REWRITE THIS SENTENCE

PROBLEM

The combination of letters i-t-s appears four times in the sentence. Does each have correct punctuation?

DISCUSSION

Let’s take these in order:

i-t-s 1

Each custom button must register its own information

This is correct. It indicates the possessive form.

i-t-s 2

such as details about it’s name

This incorrect. This is a possessive like the first one. By adding the apostrophe, the author indicates this is a contraction of two words, it and is, and that is not what the author intends.

i-t-s 3

its icon

This is correct. It indicates the possessive.

i-t-s 4

and what happens when it’s clicked

This is correct. The author indicates the contraction of it and is. You could also say:

…when it is clicked.

REVISION

Before

Each custom button must register its own information, such as details about it’s name, its icon, and what happens when it’s clicked.

After

Each custom button must register its own information, such as details about its name, its icon, and what happens when it’s clicked.

Each custom button must register its own information, such as details about its name, its icon, and what happens when it is clicked.

Example 16

REWRITE THIS SENTENCE

PROBLEM

The word navigate.

DISCUSSION

The word navigate is an acceptable word when you are talking to an American developer audience, but it gets mixed results in localization studies. I recommend you use the word go. It means the same thing in the context of the example sentence, and it is easier to read.

REVISION

Before

Navigate to the Instances & Volumes tab, and then select the correct project from the project drop-down list.

After

Go to the Instances & Volumes tab, and then select the correct project from the project drop-down list.

Example 17

REWRITE THIS SENTENCE

PROBLEM

The number 3.

DISCUSSION

In technical writing, most style guides stipulate that you spell out the numbers one through nine, and use numerals for 10 and higher. The exception to this rule is when the number is a measurement of some sort.

REVISION

Before

Based on the feature group to which the compliance gated activity belongs, combined with the user’s age band and legal country, one of 3 parental involvement levels (PIL) is identified.

After

Based on the feature group to which the compliance gated activity belongs, combined with the user’s age band and legal country, one of three parental involvement levels (PIL) is identified.

Example 18

REWRITE THIS SENTENCE

PROBLEM

Don’t use the word please for a mandatory step.

DISCUSSION

Never use the word please for a mandatory command. A command is just that—a command. When you give a command, the reader does not have an option.

This rule is especially important if your writing is headed toward a global audience where localization is involved. Some cultures may interpret the word please as an optional situation. It is your job to avoid this kind of ambiguity.

REVISION

Before

If you run Solr as a standalone mode, please do not include SOLR_MODE and ZK_HOST.

After

If you run Solr as a standalone mode, do not include SOLR_MODE and ZK_HOST.