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

Example 1

REWRITE THIS SENTENCE

PROBLEM

Today’s sentence presents a big readability problem. Need data? Here is the breakout by the Gunning Fog Index:

We have one sentence with 34 words. That is twice as long as the optimal average number of words in a sentence, which is 17.

Total word count is only one of two major problems. The other problem is the number of 3+ syllable words:

multicast
technology
operator
easily
value-added
NOTE: Hyphenated words count as a single word.
telemedicine
radio
video
conferencing
bandwidth-critical
time-critical
information

DISCUSSION

The most obvious solution is to break the sentence in half. At the very least, do that. It might be necessary to keep the 3+ syllable words, but it is very easy to divide it into two sentences.

The first sentence stops at value-added services. As for the second sentence, you have the option of creating a list or leaving the word order the same as it is now. The revision shows you both options.

Just dividing the sentence into two parts reduces the reading level to 20 years. That is the main point of today’s exercise.

REVISION

Before

By using multicast technology, a network operator can easily provide new value-added services, such as live webcasting, web TV, distance learning, telemedicine, web radio, real-time video conferencing, and other bandwidth-critical and time-critical information services.

After

By using multicast technology, a network operator easily provides new value-added services. Services include live webcasting, web TV, distance learning, telemedicine, web radio, real-time video conferencing, and other bandwidth-critical and time-critical information services.

By using multicast technology, a network operator easily provides new value-added services. Services include:

- Live webcasting
- Web TV
- Distance learning
- Telemedicine
- Web radio
- Real-time video conferencing
- Other bandwidth-critical and time-critical information services

FINAL COMMENT

An abundance of 3+ syllable words may not be a problem if your audience is familiar with the terminology. However, there is no excuse for run-on sentences. None. Keep your sentences as simple as possible. Engineering technology is hard enough without forcing the reader to negotiate gratuitously long sentences.

Example 2

REWRITE THIS SENTENCE

PROBLEM

The example sentence has three major problems (see the following screenshot):

DISCUSSION

In our rewrite, we do the following:

Reduce the readability level from 21 years to 11.
Break the sentence into two parts.
Reduce the number of 3-syllable words from 7 to 4.
Drop the word business before the word services.

NOTE: We don’t need to modify services with the word business because we already know the context is business. Therefore, it is redundant to use business as a modifier.

REVISION

Before

Inter-business traffic analysis tasks provide additional grouping capabilities because this task type combines host and application grouping into tasks that are business-service oriented.

After

Traffic analysis tasks among related businesses enable you to gather similar data into groups. This task type combines host and application grouping into tasks for services.

Example 3

REWRITE THIS SENTENCE

PROBLEM

The sentence has two independent clauses connected by and:

The value is derived at publish time
it is the same as the fullURL property of published objects.

Why is it necessary to put both independent clauses into one sentence?

DISCUSSION

Divide the sentence into two sentences. When you do that, you improve sentence readability by five years of education.

REVISION

Before

The value is derived at publish time, and it is the same as the fullURL property of published objects.

After

The value is derived at publish time. It is the same as the fullURL property of published objects.

The value is derived at publish time. This value is the same as the fullURL property of published objects.

REMARKS

You might be thinking, “Why is this guy so insistent on short, simple sentences? The example sentence is OK because both clauses are fairly short as written.”

You are right. The example sentence really is not that long. The reading level is not that high either.

Here’s the deal. In software documentation, there are going to be many sentences that are long and complicated. No matter how hard you try, you simply can’t break them up. Therefore, to improve the reading experience, you need to have some variety in sentence length.

You can’t just have one long sentence after another. If you do that, your reader might stop reading.

Leave the long, unbreakable sentences alone, and go after the low hanging fruit like this example sentence. To improve the reading experience, make the change.

Example 4

REWRITE THE BOLDFACE SENTENCE IN THIS WHITE PAPER OVERVIEW SECTION

PROBLEM

This is the problem sentence:

In this paper, we will avoid the hype surrounding big data and spare you yet another definition—just bear in mind that we view big data as representing all data that could be used to achieve better business outcomes, as well as the technologies leveraged to manage and analyze it.

As you can see, it is a loose, unstructured run-on sentence. Also, it has an extraordinarily high fog index score:

Twenty-six years of education is not going to cut it!

DISCUSSION

The first thing we do is look for ways to break up this 49-word sentence into more readable simple sentences. The author is saying three things:

In this paper we will avoid the hype surrounding big data and spare you yet another definition
we view big data as representing all data that could be used to achieve better business outcomes
[we view big data as representing all] the technologies leveraged to manage and analyze it.

Therefore, rewrite the example sentence as three smaller sentences.

REVISION

Before

After

We cut the years of education in half! Now the reading level is 13 years:

With these improvements, the beginning of the white paper is now far more readable:

It’s impossible to check your favorite technical news feeds or attend a conference these days without being exposed to several definitions of “big data” and opinions as to why it’s important. Many of these exhortations are tied to Hadoop and its cute little yellow elephant logo.

In this paper, we will avoid the hype surrounding big data and spare you yet another definition. Bear in mind that we view big data as representing all data that could be used to achieve better business outcomes. We also view big data as all the technologies leveraged to manage and analyze it. Our goal is to take a critical look at Hadoop from the mainframe perspective, and examine how new technology—available today from Veristorm—can help you solve problems that you may be struggling with. There is, indeed, a place for the elephant on the mainframe.

Example 5

REWRITE THE BOLDFACE SENTENCE IN THIS WHITE PAPER OVERVIEW SECTION

PROBLEM

In yesterday’s exercise, we changed this long sentence:

To these three shorter sentences:

Did you notice the following sentence in the Overview is no thing of beauty either? Here it is:

Our goal is to take a critical look at Hadoop from the mainframe perspective, and examine how new technology—available today from Veristorm—can help you solve problems that you may be struggling with.

Let’s get to work.

DISCUSSION

The example sentence is also saying three things:

Our goal is to take a critical look at Hadoop from the mainframe perspective
[Our goal is to] examine how new technology can help you solve problems that you may be struggling with.
[This new technology} is available today from Veristorm

Convert the long, sloppy example sentence to three shorter sentences.

REVISION

Before

After

Our goal is to take a critical look at Hadoop from the mainframe perspective. We examine how new technology can help you solve problems that you may be struggling with. Help is on the way—this technology is available today from Veristorm.

Now, combining our work from yesterday and today, here is the new and improved Overview section:

In this paper, we will avoid the hype surrounding big data and spare you yet another definition. Bear in mind that we view big data as representing all data that could be used to achieve better business outcomes. We also view big data as all the technologies leveraged to manage and analyze it. Our goal is to take a critical look at Hadoop from the mainframe perspective. We examine how new technology can help you solve problems that you may be struggling with.

Help is on the way—this technology is available today from Veristorm. There is, indeed, a place for the elephant on the mainframe.

REMARKS

We can do more with this Overview section. For example, it has 26 words with three syllables or more:

impossible
favorite
technical
conference
several
definitions
opinions
important
exhortations
elephant
surrounding
another
definition
representing
business
technologies
leveraged
analyze
critical
perspective
examine
technology
technology
available
Veristorm
elephant

Can you think of some good replacement words? Try it!