Docs Menu

Use Effective Verbs

Verbs carry the action in a sentence. 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.

Verbs are supposed to carry the action in a sentence. 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. Replace weak verbs and gerunds with strong, action-oriented verbs to restore focus to verbs from nouns. Relying on verbs rather than nouns usually makes sentences shorter, clearer, and more direct.

Use
Avoid

MongoDB leads the industry.

MongoDB 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, ...

Many nouns are built from verbs, for example, description and explanation. Such nouns are called nominalizations. Some sentences include a nominalization and a verb. Change the nominalization back into a verb and omit the existing verb to simplify those sentences.

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.

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.

Modal verbs are helping verbs that further modify the action or meaning of the main verb. If you need to use the following helping or modal verbs, use them accurately and consistently:

Modal verb
Description
Example

can

Indicates the ability to perform an action.

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

may

Indicates permission.

If you need space, you may uninstall the program.

might

Indicates probability or possibility.

A service might expose endpoints in different regions.

must

Indicates the necessity of an action.

In general, use the imperative mood. It implies the subject you and doesn't require must but still indicates necessity.

The worker must delete the message when work is done.

should

Indicates a recommendation or an expectation.

Avoid using should, because it implies uncertainty or could imply a best practice (which we might or might not want to do).

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

When possible, use single-word verbs rather than phrasal verbs (verbs followed by prepositions or adverbs).

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.

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 Cloud Provider Snapshots.

You can safely back a database up by using Cloud Provider Snapshots.

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 nouns or adjectives as verbs. 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.

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.

Verbs have singular and plural forms. Use the verb form that agrees with the subject of the sentence in number.

When the subject is
The verb is
Examples

A group of things

Singular

A variety of games is available from the App Store.

Two or more singular things connected by and

Plural

Facebook and Twitter are available from the App Store.

Two or more singular things connected by or

Singular

Your tablet or phone is all you need to play your favorite games on the go.

A singular thing and a plural thing connected by or

Singular or plural, to match the closest subject

Skype or social media apps are available from the App Store. Social media apps or Skype is available from the App Store.

Be careful not to ascribe human feelings, motivations, and actions to inanimate objects. For example, a web application doesn't know, need, remember, see, think, understand, or want.

Often, we humanize technology with anthropomorphic words. Some writers believe this makes difficult topics more understandable or relatable. These words can make the concept harder to grasp for: - Readers that are less familiar with metaphors. - Readers with English as a second language.

There are standard anthropomorphic verbs in the computer industry. For example, a software program can detect, record, require, store, check, calculate, process, accept, calculate, deny, detect, interact, interpret, listen, refuse, read, and write. You can use anthropomorphic phrases standard to the industry to avoid awkward sentence constructions, but take the time to question common usage and decide if there’s a better word.

In general, avoid phrases that convey intention or desire (such as needs or wants), intellect (thinks, knows, or realizes), or emotion (likes or cares).

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.