Simple Sentences

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

Example 1

REWRITE THIS SENTENCE

PROBLEM

This is a difficult sentence. Our job here is to take something difficult, break it down into understandable component parts, and then reassemble the content either as a long but clear single sentence or as a series of shorter sentences, each making a solitary technical point.

DISCUSSION

This is a difficult sentence largely because the author is trying to pack a lot of technical information into a concise package. The author’s writing is complicated by the insertion of a conditional statement into the heart of the sentence. Also, readability is seriously impaired by an over-the-top modifier at the beginning of the sentence.

Conditional Statements

This is the conditional statement:

if a user has been online before you enable the MAC-based VLAN function

In my opinion, it is usually best to put a conditional statement at the beginning of a sentence. It is similar to telling a user where to go on the user interface before you direct the user to select a menu item or click a button. If the sentence is too long already—which it may be in this case—it might be wise to write the conditional statement as its own sentence, and place it before the central piece of information.

Speaking of the central piece of information, here it is:

On a periodic online user re-authentication enabled port … the access device does not create a MAC-to-VLAN mapping for the user unless the user passes re-authentication and the VLAN for the user has changed.

This information is relevant only when the conditional statement applies.

Monster Modifier

An unpunctuated string of words (in bold) form a modifier:

On a periodic online user re-authentication enabled port

The noun being modified is port. it is an online-user-re-authorization-enabled port that is used periodically. Yes, all those words connected by hyphens are one unified modifier. Obviously, we need to fix that.

The monster modifier is also a good example of noun stacking. These nouns are turned into modifiers:

  • period
  • online
  • user
  • re-authentication

We will take a close look at noun stacking in a post coming soon. Stay tuned.

Sequence of Events

Here is the sequence of events in our sentence:

  1. The user must be online before you enable the MAC-based VLAN function.
  2. The user must pass re-authentication and the VLAN for the user must be changed.
  3. The access device creates a MAC-to-VLAN mapping for the user.

Got all that?

The author makes a valiant effort to cram a ton of information into a tight space. The author gets an A for effort, an A for conciseness, and a D for readability.

The following is my best effort for a rewrite. Can you do better?

REVISION

Before

On a periodic online user re-authentication enabled port, if a user has been online before you enable the MAC-based VLAN function, the access device does not create a MAC-to-VLAN mapping for the user unless the user passes re-authentication and the VLAN for the user has changed.

After

The access device can create a MAC-to-VLAN function in those situations where the user has been online before you enable the MAC-based VLAN function and the port is one that is enabled for periodic online user re-authentication.

FINAL COMMENTS

As you can see, I did not take my own advice and put the conditional statement at the beginning of the sentence. I chose to begin the sentence with the subject (access device) and verb (can create). Though it is a long sentence, the sentence structure is still very simple, with the subject and verb leading into a two-part object.

Despite my fondness for short direct sentences, I chose to keep a one-sentence format. There are occasions when the information is so complicated and when events in a sequence are so closely interrelated that you simply cannot break up the content into smaller sections.

Finally, when you run the original statement and the rewritten version through the Gunning Fog Index, you reduce the years of education required from 22 to 19 years. That’s still a lot of years. You don’t see many PH.D. graduates messing around with switches and routers. The fog index is a nice tool, but it does not take improved word order into account. My rewrite has 37 words, but the simple sentence structure of subject-verb-object makes it easier to read.

Example 2

REWRITE THESE SENTENCES

NOTE: I got a letter today from my auto insurance company. The letter contained the following two sentences.

PROBLEM

  • Comma fault
  • Bad shortcut
  • Present vs. future
  • Passive voice
  • Parentheses
  • Simple sentences

DISCUSSION

First Sentence

We have two independent clauses:

  • Note the medical authorization forms must be renewed every 90 days.
  • Therefore, we may request this form from you again, as necessary.

They are separated by a comma (before therefore). This is a comma fault.

You have two good options. You can make the example sentence two complete sentences, using a period after the first independent clause, or conclude the first independent clause with a semicolon followed by therefore and a comma.

Second Sentence

This sentence has multiple problems. Start with its length: 49 words. Break it into two sentences. Begin the second sentence after independent medical consulting firm. That improves readability.

Take the sentence out of the future tense. Rewrite it in the present tense.

Eliminate (a) wordiness and (b) misuse of parentheses (a.k.a. bad shortcut) by changing:

and the report(s) provided describing your treatment to an independent medical consulting firm

To this:

and any reports about your treatment to an independent medical consulting firm

After independent medical consulting firm, begin a new sentence with:

This firm uses….

Change the following independent clause that has active voice at the beginning, but passive voice at the end:

[This firm] uses computer analysis to compare the charges with prevailing medical costs in the specific geographical location in which treatment was rendered.

To this all-active-voice independent clause:

This firm uses computer analysis to compare your charges with prevailing medical costs for treatment in your geographical area.

Note that the awkward phrase:

with prevailing medical costs in the specific geographical location in which treatment was rendered.

Is replaced by this more straightforward revision:

with prevailing medical costs for treatment in your geographical area.

REVISION

Before

Please note the medical authorization forms must be renewed every 90 days, therefore, we will be requesting this form from you again as necessary.

As part of our medical review process, we will submit your statement for services and the report(s) provided describing your treatment to an independent medical consulting firm, which uses computer analysis to compare the charges with prevailing medical costs in the specific geographical location in which treatment was rendered.

After

1

Note the medical authorization forms must be renewed every 90 days. Therefore, we may request this form from you again, as necessary.

Or

Note the medical authorization forms must be renewed every 90 days; therefore, we may request this form from you again, as necessary.

2

As part of our medical review process, we submit your statement for services and any reports about your treatment to an independent medical consulting firm. This firm uses computer analysis to compare your charges with prevailing medical costs for treatment in your geographical area.

Example 3

REWRITE THIS SENTENCE

PROBLEM

This galloping sentence begs to be rewritten as several shorter sentences. Also, which should be replaced by that, but that particular problem goes away with the rewrite.

DISCUSSION

Let’s reduce our example sentence to its simple sentence component parts:

  • Platform and firmware security facilitates secure firmware rollback.
  • Platform and firmware security prevents unauthorized firmware updates to previous authentic versions.
  • However, you must make sure a secure mechanism or an authorized user performs the update.
  • This ensures you can avoid opening previously closed vulnerabilities.

REVISION

Before

Platform and firmware security facilitates secure firmware rollback which prevents unauthorized firmware updates to previous authentic versions unless they are performed by a secure mechanism or by an authorized user so as to avoid opening previously closed vulnerabilities.

After

Platform and firmware security facilitates secure firmware rollback. This prevents unauthorized firmware updates to previous authentic versions. However, make sure a secure mechanism or an authorized user performs the update. If you fail to do this, the update process might open previously closed vulnerabilities.

Example 4

REWRITE THIS SENTENCE

PROBLEM

This sentence has multiple problems.

  • This is a run-on sentence—it is difficult to follow. We need to break it down into shorter, more readable sentences.
  • The author is using scare quotes for emphasis or highlighting—it is not entirely clear why the author is doing this.
  • The plural form of the acronym API does not take an apostrophe.
  • Tense: Replace the past perfect tense (has not been implemented) with the present tense (are not implemented).
  • Tense: Replace the future tense (will provide) with the present tense (can get access).
  • Usage: Replace prior to with before.

DISCUSSION

Readability

The problem sentence has 65 words. It is much too long. When you break the sentence into its component parts, you can logically show four separate ideas:

  • The functionality and service are not implemented yet.
  • This document describes how users get access to the REST APIs.
  • This document outlines the benefits the REST APIs provide to users before the service project is completed.
  • The information that follows is about the RESTful APIs.

You can write at least four simple sentences to replace one long, complicated sentence.

This part of the sentence is extremely unclear:

the purpose is to document “how” the REST APIs as well as what the APIs will provide to FakeApp users

The author appears to be making two distinct points:

  • The purpose is to document how the REST APIs are provided to FakeApp users.
  • The purpose is to document what kind of benefits the REST APIs provide to FakeApp users.

Unfortunately for the reader, the author yoked the two quite-different points into one independent clause. This forces the reader to re-read this independent clause several times just to get a basic understanding.

Emphasis/Highlighting

The word how and the name of the technology FakeApp as a Web Service are in quotation marks. It appears the author is using quotation marks as scare quotes for emphasis or highlighting. We need to get rid of the quotation marks. Why? First, the author is not quoting anything. Second, if we want to give special attention to a word or phrase, we should use italics, not quotation marks. In the context of this particular problem sentence, however, it is questionable whether we need to emphasize or highlight anything. In the rewritten sentence, it seems to read OK without drawing special attention to any of the words.

Apostrophe as a Plural Form

Use an apostrophe to form a contraction (for example, it is becomes it’s, and do not becomes don’t) or to indicate possession (my father’s car). Never use an apostrophe to make a singular word, term, or acronym plural.

Tense

We don’t live in the past or the future. We live in the present. Always write in the present tense if you can.

Usage

Use before, not prior to. The phrase prior to is acceptable usage, but it connotes a stuffy, bureaucratic tone. Let’s try to avoid that tone.

REVISION

Before

[One sentence, 65 words]

This functionality and service has not been implemented as of this writing, but the purpose is to document “how” the REST API’s as well as what the API’s will provide to FakeApp users so that if a business unit needs to implement use the functionality prior to the “FakeApp as a Web Service” project being completed, information pertaining to the RESTful API’s is documented below.

After

[Five sentences, 62 words]

This document describes the RESTful APIs for the FakeApp Device Database Service. Functionality and service are not implemented yet. This document describes what benefits the REST APIs provide to FakeApp users. It explains how users can get access to these APIs. Finally, it shows a business unit how to implement RESTful API functionality before FakeApp is completed as a Web Service project.

Example 5

REWRITE THIS SENTENCE

PROBLEM

The author took three parallel statements, and strapped them together with semicolons. Grammatically, it all holds together. It is a beautiful thing—if you don’t care about readability. Unfortunately for the poor reader, it requires great effort to fight through this 41-word briar patch.

DISCUSSION

The problem sentence is very easy to break apart. It has three separate ideas:

  • To call adduser, the service needs to be granted the ADD_USER scope.
  • To call listusers, the service needs to be granted the LIST_USERS scope.
  • To call deleteuser, the service needs to be granted the DELETE_USERS scope.

The best solution would be to put these three items into a small, compact table. Because this website is about rewriting, we’ll do some wordsmithing.

I admire engineers. They love to build things. The bigger, the better. However, many engineers are fond of building long, complicated sentences. Often they cannot resist combining two or more separate thoughts into one sentence. They tie the knots; I untie the knots.

Bottom line: If there is no good reason to yoke two or more thoughts into one long sentence, don’t do it! Keep your sentences simple and, if possible, short. Your readers will thank you.

REVISION

Before

[One sentence, 41 words]

For example, in order to call adduser, the service needs to be granted the ADD_USER scope; to call listusers, the service needs to be granted the LIST_USERS scope; and to call deleteuser, the service needs to be granted the DELETE_USERS scope.

After

[Three sentences, 35 words]

For example, in order to call adduser, the service needs to be granted the ADD_USER scope. To call listusers, the service needs the LIST_USERS scope. Finally, to call deleteuser, the service needs the DELETE_USERS scope.

Example 6

REWRITE THIS SENTENCE

PROBLEM

I love this sentence!

Here is the list of errors:

  • It is a run-on sentence. We need a complete rewrite with multiple sentences.
  • The sentence begins with the passive voice. With a little effort, we can make this active voice.
  • There is a comma fault before the word however.
  • It has a mixture of present tense and future tense. The entire sentence should be in the present tense. When you break it up into shorter sentences, all sentences should be in the present tense.
  • The verb form will be written is split by the word completely.
  • For the dependent clause that begins with if the client, the word then at the beginning of the following independent clause is not necessary. Take it out.
  • The pronoun their (plural) refers back to client (singular).
  • Remove the quotation marks from the word on. Use italics to indicate emphasis.

DISCUSSION

Error 1

The sentence is divisible into three parts:

  • The fakeMessage cookie writing function happens before a login or redirection flow occurs
  • It is not guaranteed that the data will be completely written
  • If the client uses redirection in their website’s “on” events or by other means, then we recommend using a polling method

Therefore, convert this to a three-sentence paragraph.

Error 2

Change this:

The fakeMessage cookie writing function happens before a login or redirection flow occurs.

To this:

The fakeMessage cookie writing function occurs before you get a login or redirection flow.

Error 3

There is a comma fault before however. Use a semicolon or a period to separate the independent clauses. My preference is for a new sentence.

Also, add a comma after however.

Error 4

Change this:

it’s not guaranteed the data will be completely written.

To this:

it is not guaranteed the data is completely written.

Error 5

Change this:

will be completely written

To this:

is written completely

Error 6

Remove then at the beginning of the independent clause.

NOTE: You see this a lot in developer documentation. Programmers use the parallel construction if … then all the time when they write code. It is no surprise this same construction shows up in software documentation. Grammatically speaking, it is OK to use the word then. I take it out because the word then is what grammarians refer to as a understood word.

Error 7

For the phrase if the client uses redirection in their website’s “on” events, the pronoun their is incorrect. Say this instead:

 if the client uses redirection in the client website’s “on” events

Error 8

The word on appears to be in quotation marks because the author wants to emphasize it. Use italics.

REVISION

Before

The fakeMessage cookie writing function happens before a login or redirection flow occurs, however it’s not guaranteed the data will be completely written, so if the client uses redirection in their website’s “on” events or by other means, then we recommend using a polling method.

After

The fakeMessage cookie writing function occurs before you get a login or redirection flow. However, it is not guaranteed the data is written completely. If the client uses redirection in the client website’s on events or by other means, we recommend you use a polling method.

Example 7

REWRITE THIS SENTENCE

PROBLEM

You can easily divide this into two sentences. See if you can do it.

DISCUSSION

This sentence makes two points:

  • The filter allows a client to validate the token through AuthenticationPlus.
  • To do this, it uses a plug-in for the client’s web application.

For some authors, it is never enough to just write a simple declarative sentence. Clearly, our example sentence makes two points. There is no logical reason why the two points need to be linked together in a single sentence.

Write the first sentence to make a point. Stop. Write the second sentence to make another point. Stop.

Trust me: Your readers appreciate simple declarative sentences. The reader’s life is complicated enough without fighting through unnecessarily long sentences.

REVISION

Before

There is a reference ValToken filter that allows a client to validate the token through AuthenticationPlus by using a plug-in for the client’s web application.

After

The reference ValToken filter allows a client to use a plug-in for the client’s web application. The client can then perform token validation through AuthenticationPlus.

Example 8

REWRITE THIS SENTENCE

PROBLEM

This sentence takes us on quite a journey! Fasten your seat belts.

DISCUSSION

The first thing we do is break up this 51-word sentence into its component parts. We analyze each component part separately. Once we know what each component part is saying, we can put the whole shebang back together again.

Here are your component parts:

  • API owners can define assertion rules.
  • Assertion rules enable testing of the AuthenticationPlus token.
  • The testing process determines if the AuthenticationPlus token is password protected.
  • The testing process rejects a request unless the token is active.
  • The testing process enables other resources on the same API to accept the request when the token becomes inactive, but is still valid.

The long example sentence breaks out into five distinct statements. Once you lay it out like this, it starts to make more sense, doesn’t it?

This is how I would reassemble the example sentence.

The first two bullet points seem to go together. Start out with, API owners define assertion rules, and then add the restrictive clause, that enable testing of the AuthenticationPlus token. Your first sentence in the rewrite is the following:

API owners define assertion rules that enable testing of the AuthenticationPlus token.

Turn the third bullet point into a simple declarative sentence:

The testing process determines if the AuthenticationPlus token is password protected.

Turn the fourth bullet point into a simple declarative sentence:

The testing process also rejects a request unless the token is active.

Finally, conclude the rewrite as follows:

The testing process enables other resources on the same API to accept the request when the token becomes inactive, but is still valid.

REVISION

Before

[one sentence]

API owners can define assertion rules that enable testing the AuthenticationPlus token to determine if it was password authenticated and reject a request unless the token is an active token, while enabling other resources on the same API to accept the request when the token becomes inactive but is still valid.

After

[four sentences]

API owners define assertion rules that enable testing of the AuthenticationPlus token. The testing process determines if the AuthenticationPlus token is password protected. The testing process also rejects a request unless the token is active. The testing process enables other resources on the same API to accept the request when the token becomes inactive, but is still valid.

Example 9

REWRITE THE FOLLOWING SENTENCES SET IN BOLD TYPE

PROBLEM

To improve readability, we need to cut the second sentence in half. Make it two short sentences.

We have the same problem and the same solution for the third sentence.

DISCUSSION

Second Sentence

Here is the unedited second sentence:

Along with public clouds, they are leading the way to a far more agile, open environment for development and innovation, providing developers with unbridled access to the resources they need to design, build, and deploy differentiating products and services faster than ever before.

Let’s go to the Gunning Fog Index calculator.  Copy the sentence and paste it into the calculator. Click Calculate. This is what we see:

The sentence is 43 words long. According to the index, it requires about 22 years of education to read and comprehend on the first reading. The length of the sentence and the reading level are unacceptable.

The sentence begins with an independent clause (Along with public clouds, they are leading the way to a far more agile, open environment for development and innovation) and ends with a dependent clause (providing developers with unbridled access to the resources they need to design, build, and deploy differentiating products and services faster than ever before).

The obvious solution is to leave the independent clause intact. Add a period after innovation. Then rewrite the dependent clause. Here is one way you can do it:

This provides developers with unbridled access to the resources they need to design, build, and deploy differentiating products and services faster than ever before.

See, that wasn’t so hard!

Now take the two rewritten sentences and put them into the fog index calculator. The new and improved version has 13 years of required education. That is a drop of nine years.

Third Sentence

Here is the unedited third sentence:

They are also leveraging automation more extensively than ever before to solve problems and improve operational efficiencies, and they are churning out substantial cost savings in the process.

Once again, copy the sentence and paste it into the fog index calculator. Here is the result:

The reading level is 20 years. We can do better by dividing the sentence into two parts. Put a period after operational efficiencies. Drop the conjunction and. Start a new sentence with They.

The new reading level is 14 years. That’s a drop of six years.

To summarize, by changing the original five-sentence paragraph to seven sentences, we reduce the overall reading level from 17 to 14 years. Technology is hard enough without forcing the reader to re-read long, complicated sentences. Make it easy for your reader by keeping your sentences short and simple.

REVISION

Before

Private clouds have become a major catalyst for business growth and differentiation while supporting organizations’ need to manage highly sensitive information. Along with public clouds, they are leading the way to a far more agile, open environment for development and innovation, providing developers with unbridled access to the resources they need to design, build, and deploy differentiating products and services faster than ever before. They are also leveraging automation more extensively than ever before to solve problems and improve operational efficiencies, and they are churning out substantial cost savings in the process. And these benefits are just the beginning. As cloud computing moves into the hybrid era, the business impact is expected to broaden exponentially in ways that have yet to be fully understood.

After

Private clouds have become a major catalyst for business growth and differentiation while supporting organizations’ need to manage highly sensitive information. Along with public clouds, they are leading the way to a far more agile, open environment for development and innovation. This provides developers with unbridled access to the resources they need to design, build, and deploy differentiating products and services faster than ever before. They are also leveraging automation more extensively than ever before to solve problems and improve operational efficiencies. They are churning out substantial cost savings in the process. And these benefits are just the beginning. As cloud computing moves into the hybrid era, the business impact is expected to broaden exponentially in ways that have yet to be fully understood.

Example 10

REWRITE THIS SENTENCE

PROBLEM

This 54-word, run-on sentence needs a drastic make-over. As written, it requires a Ph.D. plus several years of post-doctoral education to comprehend the sentence on the first reading.

DISCUSSION

When you break the sentence into its component parts, you see three distinct ideas. Here they are:

  • If a reupload must be fixed because there is more than one CMS and the other one needs to be fixed, you have two options.
  • You can fix it by creating a new request and manually fixing the old content objects.
  • Otherwise, you can edit the request in the database and remove the CMS you don’t need.

REVISION

Before

If a reupload must be fixed because there is more than one CMS and the other one needs to be fixed, the way to fix it is to either create a new request and manually fix the old content objects or to edit the request in the database and remove the CMS not needed.

After

If a reupload must be fixed because there is more than one CMS and the other one needs to be fixed, you have two options. You can fix it by creating a new request and manually fixing the old content objects. Otherwise, you can edit the request in the database and remove the CMS you don’t need.

COMMENT: By making these changes, you reduce the readability level from 23 years to 10 years of education.

 

Example 11

REWRITE THIS PARAGRAPH


PROBLEM

The example paragraph from a white paper has two long sentences. The reading level is 21 years of education to understand everything in only one pass.

Both sentences are compound sentences. That means each sentence contains two or more simple sentences joined by connector words (for example, and, but, or or).

Remember, every compound sentence has the potential to be divided into shorter simple sentences. Let’s do that—to improve readability.

DISCUSSION

Sentence 1

Here is the first sentence (41 words):

As a best practice, enterprises should stay away from anything proprietary that might lock the development team into a single vendor’s tools or framework, as a break in that relationship might require a complete re-write and can be costly over time.

These are the four simple sentences:

  • As a best practice, enterprises should stay away from anything proprietary
  • [a proprietary tool] might lock the development team into a single vendor’s tools or framework
  • a break in the vendor relationship might require a complete re-write
  • [this relationship] can be costly over time

Sentence 2

Here is the second sentence (25 words):

Enterprises should gravitate to mobile app development environments that feature cross-platform tools and have the flexibility to support native, web, and hybrid app development efforts.

It has two simple sentences:

  • Enterprises should gravitate to mobile app development environments that feature cross-platform tools
  • [environments] have the flexibility to support native, web, and hybrid app development efforts

REVISION

Before

[two sentences, 66 words]

As a best practice, enterprises should stay away from anything proprietary that might lock the development team into a single vendor’s tools or framework, as a break in that relationship might require a complete re-write and can be costly over time. Enterprises should gravitate to mobile app development environments that feature cross-platform tools and have the flexibility to support native, web and hybrid app development efforts.

After

[six sentences, 70 words]

As a best practice, enterprises should stay away from anything proprietary. A proprietary tool might lock the development team into a single vendor’s tools or framework. A break in the vendor relationship might require a complete re-write. Further, it can be costly over time. Enterprises should move to mobile app development environments that feature cross-platform tools. These environments have the flexibility to support native, web, and hybrid app development efforts.

REMARKS

Now we are down to 12.67 years of education. Much better!

People, to improve readability, always strive to convert long complicated sentences into short simple sentences.

Example 12

REWRITE THIS SENTENCE

PROBLEM

There is no reason why this should be one long sentence. Make it three sentences.

DISCUSSION

The example sentence is saying three things:

  • The photo service has many properties configured in a client document.
  • Both the client and server can access it.
  • You can edit it easily without rebuilding the client.

If you put the original sentence into the fog index calculator, you get this result:

When you break it into three sentences, you get this result:

That is a readability improvement of eight years of education. Do you see why I keep harping on this?

REVISION

Before

The photo service has many properties configured in a client document so both the client and server can access it, and you can edit it easily without rebuilding the client.

After

The photo service has many properties configured in a client document. Both the client and server can access it. Also, you can edit it easily without rebuilding the client.

Example 13

REWRITE THIS SENTENCE


PROBLEM

Fix these issues:

  • Numbers
  • Punctuation
  • Simple Sentences
  • Word Order

DISCUSSION

Simple Sentences

The sentence makes three statements:

  • This step takes five to 30 minutes, depending on the size of the project
  • When you are done, you set up a ProjectName directory
  • [the ProjectName directory] is your FancyApp repository of that branch.

Numbers

From the Microsoft Style Guide:

Use numerals for 10 and greater. Spell out zero through nine if the number does
not precede a unit of measure or is not used as input.

Punctuation

Do not describe a range as

5-30 minutes

Say this instead:

five to 30 minutes

Word Order

The word order of the example is awkward, especially with the use of the word which in two places. See the rewritten sentence.

REVISION

Before

When this completes, which will take 5-30 minutes depending on how big the project is, you will have a ProjectName directory, which is your FancyApp repository of that branch.

After

[two sentence version]

This step takes five to 30 minutes, depending on the size of the project. When you are done, set up a ProjectName directory, which is your Git repository of that branch.

Or

[three sentence version]

This step takes five to 30 minutes, depending on the size of the project. When you are done, set up a ProjectName directory. The ProjectName directory is your Git repository of that branch.

Example 14

REWRITE THIS SENTENCE


PROBLEM

This is an interesting sentence. It is a good example of trying too hard to do too much.

The author is trying to write an all-inclusive mission statement for the FancyApp team. Sometimes with corporate mission statements, there is an irresistible compulsion to cram a lot of high-level thoughts and goals into a single sentence.

Where is it written that you are required to do that? You don’t get a Boy Scout merit badge for creating a 40-word sausage that says everything.

DISCUSSION

Rewriting

As I look at today’s example sentence, my recommendation is to make a general thesis statement, and then follow up with sentences that provide support to the thesis sentence. Instead of one long sentence, I would rewrite it as three or four shorter sentences. I would make it look like a well-written opening paragraph of an executive summary to a white paper or a proposal.

These are the key points:

  • The FancyApp team’s mission is to provide a state-of-the-art build and delivery system
  • [This build and delivery system] promotes change to the development process
  • [This build and delivery system] drives best practices for software delivery
  • FancyApp is an easy-to-use system
  • It seamlessly introduces low-risk build and deployment automation

Here is your thesis statement:

The FancyApp team’s mission is to provide an effective, state-of-the-art build and delivery system.

For the sentences that support the thesis statement, see the rewrite.

Punctuation

The example sentence has a punctuation problem. It begins with these words:

The FancyApp team’s mission is to provide an easy to use build and delivery platform….

The three words, easy to use, modify building and delivery platform. You need to connect the three words with hyphens.

In our rewrite, however, we change the word order in such a way the hyphens are no longer required.

Finally, it is incredibly easy to use.

REVISION

Before

The FancyApp team’s mission is to provide an easy to use build and delivery platform that seamlessly introduces low risk build and deployment automation with the goal of promoting change to the development process and drive software delivery best practices.

After

The FancyApp team’s mission is to provide an effective, state-of-the-art build and delivery system. Our system promotes change to the development process because it drives best practices for software delivery. FancyApp seamlessly introduces low-risk build and deployment automation. Finally, it is incredibly easy to use.

Example 15

REWRITE THIS SENTENCE


PROBLEM

Here is another needlessly complex sentence. Let’s take it apart.

DISCUSSION

The sentence makes four points:

  • A message is a single communication sent to a specific guest
  • [the guest] is referred to as a recipient
  • The recipient’s delivery profile determines which channel method is used
  • Channel methods can be email, SMS, or a push to an iPhone app

People, there is nothing wrong with confining a single idea or observation or command to a single sentence.

REVISION

Before

A message is a single communication sent to a specific guest, referred to as a recipient, via the channel method determined by their delivery profile (such as email, SMS, or a push to an iPhone app).

After

A message is a single communication sent to a specific guest. The guest is referred to as a recipient. The recipient’s delivery profile determines which channel method is used. Channel methods can be email, SMS, or a push to an iPhone app.

Example 16

REWRITE THIS PARAGRAPH


PROBLEM

We need to fix these things:

  • Begin the first sentence with an article (that is, the or a).
  • Change future tense to the present tense.
  • Make the second and third sentences complete sentences—they are fragments now.
  • Improve the word order in some places.
  • Add missing punctuation.

DISCUSSION

Sentence 1

Change this:

Person involved in maintenance will need some familiarity with Chef and the applications supported.

To this:

The person involved in maintenance needs to be familiar with Chef and the supported applications.

Sentence 2

Change this:

With enough knowledge to evaluate good version changes and questionable ones.

To this:

This person should have enough knowledge to evaluate good version changes and questionable ones.

Sentence 3

Change this:

Also the time to walk this through a testing cycle, to ensure a proper updates, before implementing in production.

To this:

Also, he or she should know how long it takes to walk this through a testing cycle. This ensures proper updates before implementing it in production.

REVISION

Before

The person involved in maintenance will need some familiarity with Chef and the applications supported. With enough knowledge to evaluate good version changes and questionable ones. Also the time to walk this through a testing cycle, to ensure a proper updates, before implementing in production.

After

The person involved in maintenance needs to be familiar with Chef and the supported applications. This person should have enough knowledge to evaluate good version changes and questionable ones. Also, he or she should know how long it takes to walk this through a testing cycle. This ensures proper updates before implementing it in production.

Example 17

REWRITE THIS SENTENCE


PROBLEM

First of all, we are missing an important verb (see in brackets):

Versions should always roll forward and never [be] changed or updated after the fact.

Now the sentence makes more sense.

Also, we have some punctuation errors to fix.

Finally, this is a procedure. We need to word the sentence so it reads like a command.

DISCUSSION

Part of the sentence is information:

Versions should always roll forward

And part of the sentence is a procedure or command:

Versions should … never [be] changed or updated after the fact.

Let’s make it two simple sentences, with the second sentence in the active voice—as a command:

  • Versions should always roll forward.
  • Don’t ever change or update versions after the fact.

REVISION

Before

Versions should always roll forward and never changed or updated after the fact.

After

Versions should always roll forward. Don’t ever change or update versions after the fact.

Example 18

REWRITE THIS SENTENCE


PROBLEM

The sentence is too long (39 words). Break it into two sentences.

DISCUSSION

Remember the formula for rewriting a long sentence?

Break the sentence into its component parts, and rebuild everything as a sequence of simple sentences. Here are your two component parts:

  • A business unit may also decide to change the look of the FakeCorp ID UI by overriding the CSS scheme of the FakeCorp ID UI
  • [It does this] by specifying a CSS-override parameter or by using an external .css override file

REVISION

Before

A business unit may also decide to change the look of the FakeCorp ID UI by overriding the CSS scheme of the FakeCorp ID UI uses by specifying a CSS-override parameter or by using an external .css override file.

After

A business unit may also decide to change the look of the FakeCorp ID UI by overriding the CSS scheme of the FakeCorp ID UI. It does this by specifying a CSS-override parameter or by using an external .css override file.

Example 19

REWRITE THIS SENTENCE


PROBLEM

We have three problems:

  • Break up this long sentence into two or three sentences
  • Change massive data clean up to massive data cleanup
  • Avoid the conditional voice when the present tense works just as well

DISCUSSION

Simple Sentences

The example sentence makes three statements:

  • The immediate mitigation was a massive data clean up of address and phone tables for those duplicates entries in the Aquarius DB
  • [the migration] resolved the problem
  • there were no identified valid reasons why a user would need these large array counts of addresses.

By breaking up the long example sentence into three shorter sentences, you reduce the reading level from 21 to 10 years of education required to understand the sentence upon the first reading.

Spelling

From the website Grammarist:

Cleanup vs. clean up

When you need a term meaning (1) to make clean or orderly, or (2) to make oneself clean, use clean up—two words. In American and Canadian English, the one-word cleanup is a noun referring to (1) a thorough cleaning or (2) the act or process of cleaning. It may also function as an adjective in phrases like cleanup crew and cleanup hitter. British writers typically use the hyphenated form—clean-up—instead. Australian and New Zealand publications are inconsistent on the matter.

Conditional Statements

Don’t say this:

…why a user would need these large array counts of addresses

Say this:

…why a user needs these large array counts of addresses

REVISION

Before

The immediate mitigation was a massive data clean up of address and phone tables for those duplicates entries in Aquarius DB which resolved the problem but there were no identified valid reasons why a user would need these large array counts of addresses.

After

The immediate mitigation was a massive data cleanup of address and phone tables for those duplicates entries in Aquarius DB. The migration resolved the problem. However, there were no valid reasons why a user needs these large array counts of addresses.

Example 20

 REWRITE THIS SENTENCE

PROBLEM

The example sentence is 66 words long! It has a reading level of 31 years of education! Break it up into shorter sentences.

DISCUSSION

Here is how you deconstruct a long sentence:

  • Capture the entire sentence and paste it into a worksheet
  • Strip out the component parts
  • Reconstruct each component part as a simple sentence
  • Reassemble the content into a sequence of simple sentences

So, here we go.

The author lays out an elaborate set of circumstances before getting to the action in the sentence. Here is the setup:

  • If client site A requires FAKECORP-TOU and ppV2
  • [if] a user creates an account and accepts these two legally required documents
  • [if] the user goes to log into client site B with that same account
  • [if] client site B requires DI-COOKIEPOLICY-NL and ppV2

The example sentence takes 43 words just to lay out all the conditions! Obviously, that is a lot of information to process.

Using the previous deconstruction formula, I suggest our example sentence logically contains three major component parts. The first two components lay out all the conditions. The third component explains the action:

  • [suppose] the client site A requires FAKECORP-TOU and ppV2, and a user creates an account and accepts these two legally required documents
  • the user then goes to log into client site B with that same account and client site B responds by requiring DI-COOKIEPOLICY-NL and ppV2
  • the system prompts the user to accept DI-COOKIEPOLICY-NL on that login  to comply with the legal requirements for logging in to client site B

Also, for clarity, add a brief introductory sentence before you write the three component parts. Say something like this:

Here is an example scenario.

REVISION

Before 

If client site A requires FAKECORP-TOU, and ppV2, and a user creates an account, and accepts these two legally required documents, and the user goes to log into client site B with that same account and client site B requires DI-COOKIEPOLICY-NL and ppV2, the system prompts the user to accept DI-COOKIEPOLICY-NL on that login  to comply with the legal requirements for logging in to client site B.

After

Here is an example scenario. Suppose the client site A requires FAKECORP-TOU and ppV2, and a user creates an account and accepts these two legally required documents. The user then goes to log into client site B with that same account and client site B responds by requiring DI-COOKIEPOLICY-NL and ppV2. In that situation, the system prompts the user to accept DI-COOKIEPOLICY-NL on that login to comply with the legal requirements for logging in to client site B.

Or 

 Here is an example scenario. Suppose you have this chain of events: 

    • Client site A requires FAKECORP-TOU and ppV2
    • A user creates an account and accepts these two legally required documents
    • The user then goes to log into client site B with that same account
    • Client site B responds by requiring DI-COOKIEPOLICY-NL and ppV2

In that situation, the system prompts the user to accept DI-COOKIEPOLICY-NL on that login to comply with the legal requirements for logging in to client site B.

COMMENT

The reading level now is 13 years of education as sentences or 11 years as a combination of sentences and a list.

Example 21

REWRITE THIS SENTENCE


PROBLEM

Issues:

  • Simple sentences
  • Which vs. that
  • Punctuation
  • Present vs. future tense

DISCUSSION

The example sentence is too long. You can easily break it up into two sentences. Also, the example has punctuation errors, but those errors go away when you rewrite as two sentences.

If you leave it as one long sentence, you need to replace which with that. However, since we are starting a new sentence, that problem also goes away.

This is optional, but, for clarity, you might put commas before and after the word potentially.

Finally, if you are describing something that happens both now and in the future, I recommend using the present tense instead of the future tense.

REVISION

Before

If the NRT account includes some personal data, the endpoint will send an email to the email address associated with this account which contains a clickback link to a page where the guest chooses a password and potentially a new username.

After

If the NRT account includes some personal data, the endpoint sends an email to the email address associated with this account. The email contains a clickback link to a page where the guest chooses a password and, potentially, a new username.

Example 22

REWRITE THIS SENTENCE

PROBLEM

The example sentence contains two basic thoughts. There is no good reason why you should not divide this long sentence into two shorter sentences.

DISCUSSION

The sentence says two things:

  • To keep the user in a logged-in state, the FakeCorpID SDK internally stores a refresh_token.
  • It uses this token periodically to get a new unexpired access_token from the FakeCorpID server.

By dividing the sentence into two parts, you reduce the fog index readability score from 23 years of education to 17 years of education. Six years of education is not trivial.

REVISION

Before

To keep the user in a logged-in state, the FakeCorpID SDK internally stores a refresh_token that it uses periodically to get a new unexpired access_token from the FakeCorpID server.

After

To keep the user in a logged-in state, the FakeCorpID SDK internally stores a refresh_token. It uses this token periodically to get a new unexpired access_token from the FakeCorpID server.

Example 23

REWRITE THIS SENTENCE

PROBLEM

This sentence is OK, but we can make it better by dividing it into two short sentences. We can make it more readable than it is now.

DISCUSSION

The example sentence expresses two thoughts:

  • The command returns the status of the entitlement, which now has an expiration date of the current time.
  • This indicates the right to access a specific digital asset is revoked.

See, that wasn’t so hard.

Such a simple change reduces the fog index by six years of education. You should always, Always, ALWAYS look for ways to improve the reading experience for the user.

REVISION

Before

The command returns the status of the entitlement, which now has an expiration date of the current time, indicating that the right to access a specific digital asset is revoked.

After

The command returns the status of the entitlement, which now has an expiration date of the current time. This indicates the right to access a specific digital asset is revoked.

Example 24

REWRITE THIS SENTENCE

PROBLEM

This meandering passive-voice sentence can be divided into three shorter sentences. 

DISCUSSION

Here is how you deconstruct a long sentence: 

  • Capture the entire sentence and paste it into a worksheet.
  • Strip out the component parts.
  • Reconstruct each component part as a simple sentence.
  • Reassemble the content into a sequence of simple sentences.

OK, let’s do that. 

Here are your three component parts:

  • The intent of the compliance section is to provide the UI with all the required information.
  • For example, it indicates what fields are required on user forms.
  • Also, it tells you what fields you can or cannot edit during an action.

Word Order

Don’t say this:

…what fields can be edited once during an action or not at all.

Say this:

…what fields you can or cannot edit during an action. 

Anthropomorphisms 

The author is attributing human qualities to (a) the compliance section and (b) the user interface (UI) by saying this: 

The intent of the compliance section is to provide the UI with all the information it needs to know….

This figure of speech is called an anthropomorphism. These are the anthropomorphic characteristics: 

  • The compliance section has an intent to provide
  • The UI has all the information it needs to know

We are talking about computer operations here, not people. Avoid anthropomorphic usage in your technical writing. 

Don’t say this: 

The intent of the compliance section is to provide the UI with all the information it needs to know. 

Say this: 

Use the compliance section to provide the UI with all the required information. 

REVISION 

Before 

The intent of the compliance section is to provide the UI with all the information it needs to know, and what fields are required on user forms as well as what fields can be edited once during an action or not at all. 

After 

Use the compliance section to provide the UI with all the required information. For example, the compliance section indicates what fields are required on user forms. Also, it tells you what fields you can or cannot edit during an action.

Example 25

REWRITE THIS SENTENCE

PROBLEM

Divide this run-on sentence into two sentences. Spell out numbers from one to nine in instances where the number is not used in a measurement.

DISCUSSION

Start a new sentence after the words required components. See the Revision section for the rewrite.

Don’t say this:

…should be around 5-10 minutes….

Say this:

…should be five to 10 minutes….

REVISION

Before

It will take a little time to download the base OS and install all required components, should be around 5-10 minutes depending on the speed of your network connection.

After

It will take a little time to download the base OS and install all required components. Download should be five to 10 minutes, depending on the speed of your network connection.

Example 26

REWRITE THIS SENTENCE


PROBLEM

This sentence has 54 words. It is way too long. Your mission is to break up this long sentence into shorter component parts.

DISCUSSION

Do you remember my formula for breaking up a long sentence into shorter sentences? OK, here it is—one more time:

  1. Capture the entire sentence and paste it into a worksheet.
  2. Strip out the component parts.
  3. Reconstruct each component part as a simple sentence.
  4. Reassemble the content into a sequence of simple sentences.

As I see it, there are two component parts:

  • Filter strategies in network traffic analysis (NTA) let you decide whether network flow records routed to NTA are processed and analyzed or discarded.
  • The packets fall into two groups:  Source or destination IP address and source or destination layer 4 port number.

You can easily turn the second bullet point into a short list. See the Revision section for the results.

REVISION

Before

Filter strategies in network traffic analysis (NTA) enable you to decide whether the network flow records that NTA receives are processed or discarded by NTA, which means you can choose to process and analyze or discard packets based on their source or destination IP address or by source or destination Layer 4 port number.

After

Filter strategies in network traffic analysis (NTA) let you decide whether network flow records routed to NTA are processed and analyzed or discarded. The packets fall into two groups:

    • Source or destination IP address
    • Source or destination layer 4 port number

Example 27

REWRITE THIS SENTENCE


PROBLEM

We need to divide the sentence into at least two parts. We need to convert the future tense to the present tense.

DISCUSSION

Simple Sentences

The FakeCorp ID does two things:

  • FakeCorp ID is an initiative to create an enterprise-wide account creation and identity management experience
  • [FakeCorp ID] institutes practices that embed the identity concept in the minds of consumers to use their identity everywhere, every time they engage with FakeCorp, both online and offline.

Now we have our two shorter sentences.

Present vs. Future Tense

Don’t say this:

[FakeCorp ID] will institute practices….

Say this:

[FakeCorp ID] institutes practices….

REVISION

Before

FakeCorp ID is an initiative to create an enterprise-wide account creation and identity management experience and will institute practices that embed the identity concept in the minds of consumers to use their identity everywhere, every time they engage with FakeCorp, both online and offline.

After

FakeCorp ID is an initiative to create an enterprise-wide account creation and identity management experience. It institutes practices that embed the identity concept in the minds of consumers to use their identity everywhere, every time they engage with FakeCorp, both online and offline.