Use effective verbs#

Verbs carry the action in a sentence, and they make your content come alive for users. To make the biggest impact with your writing, use strong, simple, action verbs. See the following sections for specific guidelines.

Use action-oriented verbs#

Verbs are supposed to carry the action in a sentence. However, when you use verbs like be, have, make, or do (and their variants), or when you use gerunds (-ing words), nouns carry the action and weaken the meaning. Shift the focus from nouns to verbs by replacing weak verbs and gerunds with strong, action-oriented verbs. Relying on verbs rather than nouns usually makes sentences shorter, clearer, and more direct.

Use

Avoid

Rackspace leads the industry.

Rackspace is the industry leader.

Role-Based Access Control (RBAC) restricts service access to authorized users.

Role-Based Access Control (RBAC) is a method of restricting service access to authorized users.

If the node can’t access the Internet, the installation process fails.

If the node doesn’t have Internet access, the installation process fails.

To create a server, specify a name, flavor, and image.

You create a server by specifying a name, flavor, and image.

When you create a server, …

When creating a server, …

Avoid nouns built from verbs#

Many nouns are built from verbs, for example, description and explanation. Such nouns are called nominalizations. Sentences that include a nominalization and a verb can often be simplified by changing the nominalization back into a verb and omitting the existing verb (as shown in the following examples).

Use

Avoid

The following table describes each of the products.

The following table provides a description of each of these products.

Install the product by completing the following tasks.

Perform the installation of the product by completing the following tasks.

The program encrypts user IDs and passwords.

The program enables the encryption of user IDs and passwords.

Use the simplest tense#

Simple verbs, such as verbs in the present tense, are easier to read and understand than complex verbs, such as verbs in the progressive or perfect tense, or verbs combined with helping verbs (such as can, may, might, must, and should).

Use

Avoid

Before you perform this task, complete the prerequisites.

Before you perform this task, you should have completed the prerequisites.

To start, three ports are open: ssh, http, and https.

To start, you are going to have three ports open: ssh, http, and https.

If you use a Red Hat distribution, iptables works a little differently.

If you are using a Red Hat distribution, iptables works a little differently.

Use helping verbs accurately#

If you need to use the following helping verbs, use them accurately and consistently:

  • Can: Use can to indicate the ability to perform an action.

  • May: Use may to indicate permission.

  • Might: Use might to indicate probability or possibility.

  • Must: You can use must to indicate the necessity of an action. However, in general, use the imperative mood, which implies the subject you and doesn’t require must but still indicates necessity.

  • Should: Use should to tell users what they ought to do. Because should implies uncertainty, avoid using it unless you explain further.

Use

You can customize Cloud Queues to achieve a wide range of performance, durability, availability, and efficiency goals.

If you need space, you may uninstall the program.

A service might expose endpoints in different regions.

The worker must delete the message when work is done.

To avoid losing a claim in the middle of processing a message, clients should periodically renew claims during long-running batches of work.

Use single-word verbs#

When possible, use single-word verbs rather than phrasal verbs (verbs followed by prepositions or adverbs). For example, use omit rather than leave out, or shorten start up to start. One-word verbs are easier to understand and to translate.

If you must use a phrasal verb, keep the parts of the verb together unless that changes the meaning of the sentence. Some acceptable phrasal verbs are back up, log in, set up, shut down, and work around.

Note

Don’t turn a phrasal verb into a single-word verb. For example, don’t use login, setup, or workaround as verbs. These single-word terms should be used only as nouns or adjectives.

Use

Avoid

Determine the type of encryption (32-bit or 64-bit) that your computer uses.

Figure out the type of encryption (32-bit or 64-bit) that your computer uses.

Click the link.

Click on the link.

You can safely back up a database by using Rackspace Cloud Backup.

You can safely back a database up by using Rackspace Cloud Backup.

Don’t use verbs as nouns or adjectives#

If a word is defined in the dictionary as a verb, don’t use it as a noun or adjective. Some verbs that are commonly misused as nouns or adjectives are configure, compile, debug, and install.

Correct

Incorrect

After installation is completed, you can configure the product.

When you complete the install, you can begin the configure.

After rubygems is compiled, the following message appears at the bottom of the output text.

When the compile process is finished, the following message appears at the bottom of the output text.

Don’t use nonverbs as verbs#

Don’t use nouns or adjectives as verbs, and don’t add verb suffixes to abbreviations, nouns, or conjunctions.

Correct

Incorrect

You can reorganize the table space.

You can REORG the table space.

Verify the change by using the ping command to contact the server.

Verify the change by pinging the server.

Some databases and search engines insert the AND operator between adjacent words in a keyword search.

Some databases and search engines AND adjacent words in a keyword search.

Navigate to the new directory.

CD to the new directory.

Use transitive verbs transitively, not intransitively#

Transitive verbs, such as display and complete, require a direct object. Intransitive verbs don’t require a direct object. Be sure to use each type of verb correctly.

To avoid using a transitive verb intransitively, you can make it passive if the performer of the action is understood or not important.

Correct

Incorrect

The product displays the available servers in the right pane.

or

The available servers are displayed in the right pane.

The available servers display in the right pane.

After the installation is completed, ensure that the FTP services are running.

After the installation completes, ensure that the FTP services are running.

Don’t humanize inanimate objects#

Be careful not to ascribe human feelings, motivations, and actions to inanimate objects. For example, a software program doesn’t know, need, remember, see, think, understand, or want. However, it can detect, record, require, store, check, calculate, and process.

The following anthropomorphic verbs are acceptable in the computer industry: accept, calculate, deny, detect, interact, interpret, listen, refuse, read, and write.

Use

Avoid

When you reference your modules in your script by using a PHP function like include() or require(), the server can find them.

When you reference your modules in your script by using a PHP function like include() or require(), the server knows where to look for them.

Mission-critical web-based applications and workloads require an HA solution.

Mission-critical web-based applications and workloads need an HA solution.

The software stores your security profile and uses it the next time you log in.

The software remembers your security profile and uses it the next time you log in.