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
1
Before
Utilize a database for distribution lists.
After
Use a database for distribution lists.
2
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.
3
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
1
This resource defines the feature type (i.e., Boolean, String, Int, and enumerated types).
2
This enables the guest to update his or her information via the UI.
3
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.
4
For ISP blocks (WarmMail, FutureOfAwesome, etc.), typically the incidents trigger an alert.
After
1
This resource defines the feature type (that is, Boolean, String, Int, and enumerated types).
2
This enables the guest to update his or her information through the UI.
Or
This enables the guest to update his or her information by using the UI.
3
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.
4
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.
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!
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.
Or
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.
Or
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.
Or
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.