IMPORTANT: This topic is about direct speech. However, all of the following examples contain discussions of multiple subjects—not just direct speech. Therefore, in addition to direct speech, you are going to learn a lot of different things about good writing and rewriting.
Example 1
REWRITE THIS PARAGRAPH
PROBLEM
Here are the problems
- Fix the convoluted, roundabout language—we need to use direct speech in the active voice.
- Replace which with that.
- Fix the run-on sentences—break long sentences into shorter sentences.
- Instead of making a recommendation, simply tell the reader what to do. Recommendations and polite suggestions might be interpreted as optional.
DISCUSSION
The following revision speaks for itself.
REVISION
Before
When a page which uses the SnappyApp is browsed to or refreshed, and ifhiddenAutoLogin is turned on, then it will attempt to check the logged-in state of the user, and if the user needs to be logged in, it will automatically sign them in. When this is complete the SnappyApp will call the loginSuccess function. This function may modify the webpage to display a logged-in state, but sometimes this process takes some time. To prevent a user from temporarily seeing a logged-out state before being logged in, we recommend using code similar to this.
[a block of code follows]
After
When the user opens or refreshes a page that uses SnappyApp, and hiddenAutoLogin is turned on, the system checks the logged-in state of the user. If the user is not logged in, the system does that automatically. SnappyApp then calls the loginSuccess function. This function modifies the webpage to indicate the user is logged in. However, there may be a long wait before the user gets the message he or she is actually logged in. To ensure the user does not see a logged-out state before being logged in, use the following code.
[a block of code follows]
Or if you use the second-person singular (You)
When you open or refresh a page that uses SnappyApp, and hiddenAutoLogin is turned on, the system checks your logged-in state. If you are not logged in, the system does that automatically. SnappyApp then calls the loginSuccess function. This function modifies the webpage to indicate you are logged in. However, there may be a long wait before you get the message you are actually logged in. To ensure you do not see a logged-out state before being logged in, use the following code.
[a block of code follows]
Example 2
REWRITE THIS SENTENCE
PROBLEM
Don’t say, have replaced … and [have] included….
Say, replace … and include….
DISCUSSION
Be direct with your reader. Don’t fill up your sentences with weaselly language. Use the present tense whenever possible!
See the Revision section for the rewrite.
REVISION
Before
The second example shows how the URI might look after you have replaced the appropriate values and included the required HTML-formatted @ symbol in the URL.
After
The second example shows how the URI might look after you replace the appropriate values and include the required HTML-formatted @ symbol in the URL.
Example 3
REWRITE THIS SENTENCE
PROBLEM
The author is giving a command in the most roundabout way imaginable. The author’s use of the passive voice lacks forcefulness.
Also, we have two code references (eTag and get). We need to put those words in monospace type.
DISCUSSION
When you give a command, begin with the tool:
Use the eTag returned by the get call [to do something].
Always use the active voice when you write a command.
REVISION
Before
Any persisted data should be saved and the update retried using the eTag returned by the get call.
After
Use the eTag returned by the get call to save any persisted data and retry the update.
Example 4
REWRITE THIS SENTENCE
PROBLEM
The shortest distance between two points is a straight line. This sentence violates that principle in two places (in brackets):
The second example shows how the URI [might look] after you [have replaced] the appropriate values.
DISCUSSION
might look
Don’t say this:
The second example shows how the URI might look….
Say this:
The second example shows how the URI looks….
COMMENT: Don’t turn a straightforward descriptive sentence into a conditional statement—unless you are describing a true conditional situation. Use the present tense.
have replaced
Don’t say this:
…after you have replaced the appropriate values.
Say this:
…after you replace the appropriate values.
COMMENT: Whenever possible, use direct, present-tense speech when you communicate with your readers.
REVISION
Before
The second example shows how the URI might look after you have replaced the appropriate values.
After
The second example shows how the URI looks after you replace the appropriate values.
Example 5
REWRITE THIS PARAGRAPH
PROBLEM
The example paragraph is poorly written because the author does not speak plainly. See the Discussion section.
DISCUSSION
Let’s lay out these three sentences and examine them one by one.
Sentence 1
NTA is an environment that you configure to have visibility to the network flow data that the devices in your network provide.
This sentence is very awkward. Here is a clear rewrite.
NTA enables you to view the network flow data provided by the devices in your network.
Sentence 2
NTA out-of-the-box provides the potential for network flow data collection, analysis, and reporting and you realize this potential through your configuration of NTA.
More awkwardness. Here is a better way to say it.
Out-of-the-box configuration of NTA provides the potential of network flow data collection, analysis, and reporting.
Sentence 3
This requires an understanding network flow records, the devices in your environment that generate network flow records, and how to configure NTA to process the data and present the reports you need.
The author is still using an elaborate, roundabout way of saying things. In my rewrite, I have two sentences out of the original one.
NTA users must have an understanding of network flow records and the devices in the environment that generate network flow records. Also, users need to know how to configure NTA to process the data and present reports.
REVISION
Before
NTA is an environment that you configure to have visibility to the network flow data that the devices in your network provide. NTA out-of-the-box provides the potential for network flow data collection, analysis, and reporting and you realize this potential through your configuration of NTA. This requires an understanding network flow records, the devices in your environment that generate network flow records, and how to configure NTA to process the data and present the reports you need.
After
NTA enables you to view the network flow data provided by the devices in your network. Out-of-the-box configuration of NTA provides the potential of network flow data collection, analysis, and reporting. NTA users must have an understanding of network flow records and the devices in the environment that generate network flow records. Also, users need to know how to configure NTA to process the data and present reports.
Example 6
REWRITE THIS SENTENCE
PROBLEM
The first part of the sentence is not as concise as if could be. See the words in brackets.
Let them know [what all needs to be included] if there are multiple files going out at the same time.
DISCUSSION
Replace the verbose part of the sentence with more direct language.
REVISION
Before
Let them know what all needs to be included if there are multiple files going out at the same time.
After
Let them know what to include if there are multiple files going out at the same time.
Example 7
REWRITE THIS SENTENCE
PROBLEM
The example sentence is supposed to be a procedure. Instead, it sounds as if the author is merely passing along nice-to-know information.
DISCUSSION
Be direct with your reader. Say this:
Use the API module to expose your service through the API management gateway.
REVISION
Before
The API module is the module you will use to expose your service through the API management gateway.
After
Use the API module to expose your service through the API management gateway.
Example 8
REWRITE THIS SENTENCE
PROBLEM
You can eliminate the words in brackets:
When editing the address, [you must] specify one of the following address types.
DISCUSSION
Once again—be direct. See the Revision section for the slimmed-down sentence.
REVISION
Before
When editing the address, you must specify one of the following address types.
After
When you edit the address, specify one of the following address types.
Example 9
REWRITE THIS SENTENCE
PROBLEM
The sentence gets off to a very wobbly start because the author doesn’t speak plainly. The suspect part of the sentence is in brackets:
[This workflow is intended to be used in cases] when you need to assure the user is in a high trust state.
DISCUSSION
The example sentence has a passive, roundabout beginning:
This workflow is intended to be used….
It sounds weak and timid. A better way to say it is to begin with the action:
Use this workflow….
Also, it is not clear what the word assure means in this context. Question: Are you assuring the user or are you assuring yourself about the user? Answer: What the author means is letting the user know everything is OK. See the Revision section for a better way to say it.
REVISION
Before
This workflow is intended to be used in cases when you need to assure the user is in a high trust state.
After
Use this workflow when you need to assure the user that he or she is in a high trust state.
Example 10
REWRITE THIS SENTENCE
PROBLEM
The phrase:
…after they have signed into FakeCorpID.
DISCUSSION
Don’t say this:
…after they have signed in to FakeCorpID.
Say this:
…after they sign in to FakeCorpID.
The phrase have signed in is more words and less direct. Be straightforward with your readers. Stick to the present tense.
REVISION
Before
Users start out in a high trust state for 30 minutes after they have signed in to FakeCorpID.
After
Users start out in a high trust state for 30 minutes after they sign in to FakeCorpID.
Example 11
REWRITE THIS SENTENCE THAT INTRODUCES A LIST
PROBLEM
The sentence has two clauses. It begins with the dependent clause,
After a user has chosen a primary account….
And ends with the independent clause,
the following behaviors are enabled:
You can use more forceful language to rewrite both clauses.
DISCUSSION
Dependent Clause
Don’t say this:
After a user has chosen a primary account…
Say this:
After a user choses a primary account…
Independent Clause
Don’t say this:
…the following behaviors are enabled:
Question: Who or what is doing the enabling?
Answer: The system, the computer, the program, the app, or something else—identify the “actor” and make the actor the subject of the sentence.
Say this:
…the system enables the following behaviors:
REVISION
Before
After a user has chosen a primary account, the following behaviors are enabled:
After
After a user choses a primary account, the system enables the following behaviors:
Example 12
REWRITE THIS SENTENCE
PROBLEM
This sentence, though brief, needs a lot of work. Here are the problems:
- It uses a conditional mood statement instead of the straightforward present tense.
- The word alternately is an ugly polysyllabic word. Besides that, alternately is not a synonym for on the other hand, which is what the author intends to say. The meaning is different.
- The sentence contains some wordiness.
DISCUSSION
Conditional Mood
Don’t say this:
…this would indicate that you need to provide…
Say this:
…you must provide…
Wordiness
The wordy passage is in brackets:
Alternatively, if you see a response such as the one below, [this would indicate that you need to provide] those two legal options to the user.
Usage
Use of the word alternately is confusing in this context. It implies you may have another option. You don’t. What the author really means to say is this: If you get the following response, you must take a specific action.
Don’t say this:
Alternately….
Say this:
On the other hand….
REVISION
Before
Alternatively, if you see a response such as the one below, this would indicate that you need to provide those two legal options to the user.
After
On the other hand, if you see a response such as the one that follows, you must provide those two legal options to the user.
