Can Do Something

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

Example 1

REWRITE THIS SENTENCE

PROBLEM

Instead of saying:

It can deliver content

Say this:

It delivers content.

DISCUSSION

Use direct speech. Saying you can do something could be construed as an option.

Suppose you need to order someone to drive to Seattle to pick up a package at the home office. You don’t say:

You can drive to Seattle and pick up the package.

You say:

Drive to Seattle and pick up the package.

Do you see the difference? Remember, procedures are more like giving orders than making suggestions.

Statements that are less than clear cut are a problem when your documentation is translated into other languages. Translators like unambiguous statements.

REVISION

Before

It can deliver content based on device-specific context and access type.

After

It delivers content based on device-specific context and access type.

Example 2

REWRITE THIS SENTENCE

PROBLEM

In technical writing, we tell people what to do and how to do it. When you put this particular sentence back into its original context in the documentation, it is obvious the user must make configuration changes. It is not an option. Therefore, we should not phrase it as a suggestion if the user is in the mood to make changes.

DISCUSSION

Avoid the helping verb can as much as possible. Use the main verb and skip the can construction in situations where the user does not have options.

Use plain speech and be direct.

REVISION

Before

You can configure the spinner size and color to complement the specified color and graphic theme.

After

Configure the spinner size and color to complement the specified color and graphic theme.

Example 3

REWRITE THIS SENTENCE

PROBLEM

The problem part of the sentence follows the comma. Currently, the independent clause of the sentence looks like this:

You can call the guestAccountMapping API using the optional query parameter overwrite.

DISCUSSION

Can Do Something

Don’t use the can do something construction if you are commanding the user to perform an action. Skip the word can and simply use the main verb. In this sentence, the main verb is to call.

Word Order in a Procedure

Start by instructing the user to pick up the tool to use. In this sentence, the tool is the optional query parameter overwrite. Say this:

Use the optional query parameter overwrite to call [blah blah blah].

REVISION

Before

If you do not need to notify a user you are deleting the account mapping, you can call the guestAccountMapping API using the optional query parameter overwrite.

After

If you do not need to notify a user you are deleting the account mapping, use the optional query parameter overwrite to call the guestAccountMapping API.

Example 4

REWRITE THIS SENTENCE

PROBLEM

This sentence is nearly incoherent. We need to isolate the component parts of the example sentence, and then reconstruct the whole shebang.

DISCUSSION

Simple Sentences

What are the component parts of the example sentence? Here is the break-out:

  • Marketing list changes trigger partial profile updates.
  • What do you do if you want to avoid triggering a partial profile update when there is a change?
  • A business unit sets the ppuRule attribute in its client configuration.

Word Order

Start with a simple statement of fact:

Marketing list changes trigger partial profile updates.

For the rest of the sentence, begin with this dependent clause:

To avoid triggering a partial profile update when there is a change

Add a comma at the end of the dependent clause, and then finish with this independent clause:

a business unit sets the ppuRule attribute in its client configuration.

Can Do Something

Don’t say this:

Business units … can do so by setting….

Say this:

…a business unit sets….

NOTE: I changed the subject from business units (plural) to a business unit (singular) because, collectively, business units do not set attributes. Each individual business unit sets its own attributes.

REVISION

Before

Business units that want to suppress a partial profile update from being triggered whenever there is a change in marketing lists available, can do so by setting the ppuRule attribute in their client configuration.

After

Marketing list changes trigger partial profile updates. To avoid triggering a partial profile update when there is a change, a business unit sets the ppuRule attribute in its client configuration.

Example 5

REWRITE THIS SENTENCE

PROBLEM

I see four problems with the example sentence:

  • Can do something
  • Latin phrases
  • Passive voice
  • Word order

DISCUSSION

Can Do Something

I can do lots of things if I am in the mood. For example, I can run for president in 2016. After all, I was born in the USA and I am way over the minimum age. I may or may not do that. I’ll have to think about it.

Do you see my point?

Look once more at the example sentence:

Tree fields can be configured via custom metadata searchLeavesOnly to only search for tree leaves when using the typeahead.

To say you can do something indicates you have some sort of option. But where is the option here? Is there more than one way to configure the tree fields? Actually, no. There is only one way to configure the tree fields. You do it by using the custom metadata searchLeavesOnly.

Latin Phrases

Technically, this is not a “problem.” It is my editorial preference to use English words instead of Latin phrases. Using Latin phrases is OK in many if not most work organizations. Follow the style standards of your organization.

If authors always used Latin phrases correctly, I would not have any complaints. However, many authors obviously don’t know the correct meanings of etc., i.e., e.g., and via. I get tired of making changes. In my work organization, I tell my authors not to use Latin phrases. That way our readers are never befuddled by the misuse of a Latin phrase.

Passive Voice

The user is the actor in this configuration drama. Make the user the subject of the sentence. Setting the sentence in the active voice is especially important because in this example you are writing a procedure. I cannot think of any situation where it is better to put a procedure in the passive voice.

Word Order

When writing a procedure, I think it is preferable to set the stage before you tell the reader what to do. For example, to save a document, you need to tell the reader to go to the File menu on the user interface first. Similarly, you tell the reader what tool to use first before you tell him or her what to do with the tool.

So, in this example, set the stage first. Say this:

To only search for tree leaves when using the typeahead,

Before you give the procedure:

use custom metadata searchLeavesOnly to configure tree fields.

REVISION

Before

Tree fields can be configured via custom metadata searchLeavesOnly to only search for tree leaves when using the typeahead.

After

To only search for tree leaves when using the typeahead, use custom metadata searchLeavesOnly to configure tree fields.

Example 6

REWRITE THIS SENTENCE

PROBLEM

When giving explicit instructions to a user, skip the can do something construction.

DISCUSSION

What’s the different between You can do something and do something? The first sentence sounds like you have an option. The second is a command.

Sometimes, the can do something construction presents localization problems because, in some cultures, users are confused by what seems like an ambiguous statement. When you write a mandatory procedure, do not leave any doubt. Make a command sound like a command.

REVISION

Before

You can download the latest ContentMigratorDeployment.zip from on the Content Migrator 4.2 page.

After

Download the latest ContentMigratorDeployment.zip from on the Content Migrator 4.2 page.