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

Example 1

REWRITE THIS TEXT

PROBLEM

The bulleted items lack parallelism.
The end punctuation of the bulleted items is not consistent.
All sentences and bulleted items should be in the active voice unless there is a compelling reason for passive voice.
The term well earthed may not be understood by the American English audience. This is a localization issue.

DISCUSSION

Parallelism

We have six bullet points. Bullet points 3 and 4 are complete sentences. The first two and last two bullet points are not complete sentences. They are fragments. They are fragments because they complete the introductory line, Mount your switch in a rack and make sure….

For example, the first bullet point reads as follows:

Mount your switch in a rack and make sure adequate clearance is reserved at the air inlet and exhaust vents for ventilation.

Here is the iron-clad rule: All bullet point must be either standalone complete sentences or fragments that complete the introductory line. You need to make a decision one way or the other. Of course, if you go with complete sentences, you must also revise the introductory line.

My advice to you is to go with complete sentences. Let me explain.

You see a lot of introductory lines that lead into fragmented bullet points in sales and marketing material where the bullet points tend to be concise. This is fine for fast-paced PowerPoint presentations.

In engineering documentation, however, bulleted lists typically contain lots of complex technical information. Thus, if the bulleted item is a long-winded fragment that completes the introductory line, you put a heavy burden on the reader to comprehend everything, especially if the introductory is more than a few lines up the page.

In the revision that follows, I am going with complete sentences.

End Punctuation

The author forgot to put a period at the end of the second bullet point. In effect, all of the bulleted items are complete sentences, whether they complete the introductory line or they stand alone. For that reason, each bullet point requires a period.

End punctuation for list items must be consistent throughout. It’s all or nothing.

Active Voice

Wherever possible, change the passive voice to active voice.

Well Earthed?

The American English reader is more familiar with the term well grounded. Make that change so it is perfectly clear to your American audience.

This a good example of a localization problem. Here is the backstory for our example.

The company that made these switches and produced the original documentation is based in China. What you see here is an English translation from the Chinese. I don’t know if the translator is British-educated or what, but you must find a more suitable word or expression for the American reader.

REVISION

Before

EXAMINING THE INSTALLATION SITE

The [first switch] and [second switch] switches must be used indoors.

Mount your switch in a rack and make sure:

- Adequate clearance is reserved at the air inlet and exhaust vents for ventilation.
- The rack has a good ventilation system
- Identify the hot aisle and cold aisle at the installation site, and make sure that ambient air flows into the switch from the cold aisle and exhausts to the hot aisle.
- Identify the airflow designs of neighboring devices, and prevent hot air flowing out of the bottom device from entering the top device.
- The rack is sturdy enough to support the switch and its accessories.
- The rack is well earthed.

After

EXAMINING THE INSTALLATION SITE

It is important that you never use the [first switch] and [second switch] switches outdoors. These switches are for indoor use only.

Mount your switch in a rack, and make sure you do the following:

- Provide adequate clearance at the air inlet and exhaust vents for ventilation.
- Ensure the rack has a good ventilation system.
- Identify the hot aisle and cold aisle at the installation site, and make sure that ambient air flows into the switch from the cold aisle and exhausts to the hot aisle.
- Identify the airflow designs of neighboring devices, and prevent hot air flowing out of the bottom device from entering the top device.
- Ensure the rack is sturdy enough to support the switch and its accessories.
- Verify the rack is well grounded.

Example 2

REWRITE THIS SENTENCE

PROBLEM

Convert this meandering run-on sentence into a list
The word More is an interface feature, which means it should be in bold type—it should not be in quotation marks

DISCUSSION

The sentence is a loose collection of ideas and observations. These are the facts stated in the sentence:

The administrator can specify a different order of context menus for content in the workbench, collection, and reference fields.
The administrator can specify a default for all other content grid context menus.
The administrator can add a new More sub-menu for each type of context menu.

REVISION

Before

The administrator can also specify a different order of context menus for content in the workbench, collection and reference fields and a default for all other content grid context menus, as well as add a new “More” sub-menu for each type of context menu.

After

The administrator can do the following:

- Specify a different order of context menus for content in the workbench, collection, and reference fields.
- Specify a default for all other content grid context menus.
- Add a new More sub-menu for each type of context menu.

Example 3

REWRITE THIS BULLET LIST

PROBLEM

The five bullet points lack parallelism. Can you make them all identical in structure?

DISCUSSION

From the University of Nevada, Las Vegas, Writing Center:

Parallelism is the use of similar patterns of words (or grammatical forms) to express similar or related ideas or ideas of equal importance. Using parallel structures creates rhythm and balance and enables the writer to present ideas clearly, concisely, and smoothly. Perhaps even more important, parallelism can help a writer highlight or emphasize information or make a powerful point. Without parallelism, writing can become clunky, awkward, and needlessly confusing. With it, reading can become easy to understand, pleasing to the ear, and even persuasive.

We need to make each one of the five bullet points exactly the same in structure. I will give you two different looks.

REVISION

Before

There are five use cases to verify:

- Fake operation (FO) has entitlement in DB—entitlement not expired
- FO has entitlement in DB—entitlement is expired in DB, but entitlement not expired at the carrier
- FO has entitlement in DB—entitlement is expired in DB, and entitlement is expired at the carrier
- FO does not have entitlement in DB—entitlement is not expired at the carrier
- FO does not have entitlement in DB—entitlement is expired or not found at the carrier

After

[with verbs after the dash]

There are five use cases to verify:

- Fake operation (FO) has entitlements in DB—entitlement is not expired
- FO has entitlements in DB—entitlement is expired, but entitlement is not expired at the carrier
- FO has entitlement in DB—entitlement is expired in DB and at the carrier
- FO does not have entitlement in DB—entitlement is not expired at the carrier
- FO does not have entitlement in DB—entitlement is expired or is not found at the carrier

[without verbs after the dash]

There are five use cases to verify:

- Fake operation (FO) has entitlements in DB—entitlement not expired
- FO has entitlements in DB—entitlement expired, but entitlement not expired at the carrier
- FO has entitlement in DB—entitlement expired in DB and at the carrier
- FO does not have entitlement in DB—entitlement not expired at the carrier
- FO does not have entitlement in DB—entitlement expired or not found at the carrier

Example 4

REWRITE THIS PARAGRAPH AS A LIST

PROBLEM

It is much easier to digest the information when it is arranged as a list.

DISCUSSION

There are several ways to make a list of bullet points:

You can have each list item contain the language already there in the original.
You can have each list item begin with IP address followed by a dash.
You can have each list item begin with IP address followed by a colon.

In our rewrite, we are going to look at all three versions.

REVISIONS

Before

The IP address of the access device must be the same as the source IP address of the CIRCLE packets sent from the switch. Make sure you select he address in this order: The IP address specified with nas-ip on the switch; the IP address specified with circle nas-ip on the switch; and the IP address of the outbound interface (the default).

After

The IP address of the access device must be the same as the source IP address of the CIRCLE packets sent from the switch. Make sure you select the address in this order:

- IP address specified with nas-ip on the switch
- IP address specified with circle nas-ip on the switch
- IP address of the outbound interface (the default)

The IP address of the access device must be the same as the source IP address of the CIRCLE packets sent from the switch. Make sure you select the address in this order:

- IP address—specified with nas-ip on the switch
- IP address—specified with circle nas-ip on the switch
- IP address—the outbound interface (the default)

The IP address of the access device must be the same as the source IP address of the CIRCLE packets sent from the switch. Make sure you select he address in this order:

- IP address: specified with nas-ip on the switch
- IP address: specified with circle nas-ip on the switch
- IP address: the outbound interface (the default).

NOTE: Words are never capitalized after a dash or colon unless the word is a proper noun. The information after the dash or colon is considered to be part of the same sentence.

Example 5

REWRITE THIS SENTENCE

PROBLEM

This 49-word sentence is a true word salad. We need to completely reorganize it.

DISCUSSION

Let’s start with the basic information. What is the author trying to say? The author is describing three types of errors: ADVISORY, ACTIONABLE_INPUT, and FAILURE_BY_DESIGN.

That’s it!

Now that we know the gist of the sentence, I recommend we reorganize the information as a bullet list.

REVISION

Before

Errors that are of an informative, yet not blocking nature are ADVISORY, others might be ACTIONABLE_INPUT for which the calling system should ask the user to provide or correct input, or FAILURE_BY_DESIGN when a business rule, such as permissions, are not being met in order to service a request.

After

There are three types of errors:

- An ADVISORY error is an Informative error that does not block.
- An ACTIONABLE_INPUT error is one in which the calling system asks the user to provide or correct input.
- A FAILURE_BY_DESIGN error is one in which a business rule, such as permissions, is not met in order to service a request.

Example 6

REWRITE THIS BULLET LIST FROM A RELEASE NOTES DOCUMENT

PROBLEM

Generally speaking, release notes are less formal and more casual than typical documentation. When your company releases a new product or an upgrade to an existing product, the release notes summarize the basics for managers and IT personnel alike, using a friendly, familiar style of writing.

Nevertheless, the principles of good expository writing still apply. One of those principles is parallel grammatical construction.

As you can see, the bullet items are not consistently parallel. You need to fix that.

DISCUSSION

When you fix a list that is not parallel, you need to come up with a strategy in which all of the bullet items have a consistent grammatical style. You really have to put on your thinking cap and find a way where each and every bullet item is the same grammatically.

In this example for today, my recommendation is to begin each bullet item with a past tense verb form. It is past tense because your company, FakeCorp, did all these things for this release:

Inserted
Removed
Added
Enabled
Updated
Moved
Renamed
Configured

Let’s take these bullet items one by one.

Don’t say this:

Inserts floating button bar

Say this:

Inserted floating button bar

This is OK:

Removed email support button from troubleshooting page

Don’t say this:

Search content by date range for created and last modified dates

Say this:

Enabled content search by date range for created and last modified dates

Don’t say this:

Always show the Quick Search box (configurable, off by default)

Say this:

Added the Quick Search box (configurable, off by default), which always shows

Don’t say this:

Auto open cloned object (configurable, off by default)

Say this:

Added auto open cloned object (configurable, off by default)

Don’t say this:

Ability to share saved searches

Say this:

Enabled the sharing of saved searches

Don’t say this:

Drag and drop to and from reference properties

Say this:

Added drag and drop to and from reference properties

Don’t say this:

Support for editing unmanaged external file properties

Say this:

Added support for editing unmanaged external file properties

Don’t say this:

Tri-state confirmation box for administration tools when navigating away from unsaved changes

Say this:

Added tri-state confirmation box for administration tools when navigating away from unsaved changes

This is OK:

Added typeahead to Editor field in search by user

Don’t say this:

Ability to publish or unpublish child content from a collection property

Say this:

Enabled publish or unpublish child content from a collection property

Don’t say this:

My Locked Content left navigation module updated to expand, which allows you to select All Locked Content, My Locked Content or Content locked by a specific user

Say this:

Updated my Locked Content left navigation module to expand—this allows you to select All Locked Content, My Locked Content or Content locked by a specific user

Don’t say this:

Section browser refreshes root sections when you collapse and expand the module

Say this:

Enabled section browser to refresh root sections when you collapse and expand the module

Don’t say this:

Ctrl+F for find and replace in all text fields

Say this:

Added Ctrl+F for find and replace in all text fields

This is OK:

Moved event search link to a tab under More search options

This is OK:

Renamed Cancel button to Close in the content edit form

Don’t say this:

When you close the content, the home screen appears if the previous view is not a data grid or scheduled task admin tool, which can be configured

Say this:

When you close the content, configured the home screen to appear if the previous view is not a data grid or scheduled task admin tool (which can be configured)

Don’t say this:

Maximize button in markup editor

Say this:

Added a maximize (+) button in the markup editor

Don’t say this:

Add label added to context menu of child content in collections and references

Say this:

Added label to context menu of child content in collections and references

Don’t say this:

Open in new tab added to context menu of child content in collections and references

Say this:

Added open in new tab to context menu of child content in collections and references

Don’t say this:

Lock status polling (configurable. off by default)

Say this:

Added lock status polling (configurable. off by default)

REVISION

Before

New features

- Inserts floating button bar
- Removed email support button from troubleshooting page
- Search content by date range for created and last modified dates
- Always show the Quick Search box (configurable, off by default)
- Auto open cloned object (configurable, off by default)
- Ability to share saved searches
- Drag and drop to and from reference properties
- Support for editing unmanaged external file properties
- Tri-state confirmation box for administration tools when navigating away from unsaved changes
- Added typeahead to Editor field in search by user
- Ability to publish or unpublish child content from a collection property
- My Locked Content left navigation module updated to expand, which allows you to select All Locked Content, My Locked Content or Content locked by a specific user
- Section browser refreshes root sections when you collapse and expand the module
- Ctrl+F for find and replace in all text fields
- Moved event search link to a tab under More search options
- Renamed Cancel button to Close in the content edit form
- When you close the content, the home screen appears if the previous view is not a data grid or scheduled task admin tool, which can be configured
- Maximize button in markup editor
- Add label added to context menu of child content in collections and references
- Open in new tab added to context menu of child content in collections and references
- Lock status polling (configurable. off by default)

After

New features

- Inserted floating button bar
- Removed email support button from troubleshooting page
- Enabled content search by date range for created and last modified dates
- Added the Quick Search box (configurable, off by default), which always shows
- Added auto open cloned object (configurable, off by default)
- Enabled sharing of saved searches
- Added drag and drop to and from reference properties
- Added support for editing unmanaged external file properties
- Added tri-state confirmation box for administration tools when navigating away from unsaved changes
- Added typeahead to Editor field in search by user
- Enabled publish or unpublish child content from a collection property
- Updated my Locked Content left navigation module to expand—this allows you to select All Locked Content, My Locked Content or Content locked by a specific user
- Enabled section browser to refresh root sections when you collapse and expand the module
- Added Ctrl+F for find and replace in all text fields
- Moved event search link to a tab under More search options
- Renamed Cancel button to Close in the content edit form
- When you close the content, configured the home screen to appear if the previous view is not a data grid or scheduled task admin tool (which can be configured)
- Added a maximize button (+) in the markup editor
- Added label to context menu of child content in collections and references
- Added open in new tab to context menu of child content in collections and references
- Added lock status polling (configurable. off by default)

Example 7

REWRITE THIS PARAGRAPH

PROBLEM

The main problem with this paragraph is the second sentence (in bold):

The Headline News Service is an external stateless workflow driven REST service that performs many actions on the behalf of editors. The service provides easy social media credential management, performs the step by step processes necessary for curating breaking news within the CMS, and integrates with numerous external endpoints such as Bit.ly, Twitter, and Facebook. The rationale behind a separate service is to minimize the impact on the customer’s content model, decouple the limitations of CMS listener events from workflow actions, and simplify the upgrade or hotfix process by allowing the CMS to remain always on.

In my opinion, the information in the highlighted sentence is better served by a list.

You could also make a case for a list in the last sentence, but we will leave it as-is in this exercise.

DISCUSSION

Make a list out of the second sentence. See the Revision section for the results.

REVISION

Before

The Breaking News Service is an external stateless workflow driven REST service that performs many actions on the behalf of editors. The service provides easy social media credential management, performs the step by step processes necessary for curating breaking news within the CMS, and integrates with numerous external endpoints such as Bit.ly. Twitter, and Facebook. The rationale behind a separate service is to minimize the impact on the customer’s content model, decouple the limitations of CMS listener events from workflow actions, and simplify the upgrade or hotfix process by allowing the CMS to remain always on.

After

The Breaking News Service is an external stateless workflow-driven REST service that performs many actions on the behalf of editors. The service does the following:

- Provides easy social media credential management
- Performs the step-by-step processes necessary for curating breaking news in the CMS
- Integrates with numerous external endpoints such as Bit.ly. , Twitter, and Facebook

The rationale behind a separate service is to minimize the impact on the customer’s content model, decouple the limitations of CMS listener events from workflow actions, and simplify the upgrade or hotfix process by allowing the CMS to remain always on.

Example 8

REWRITE THIS PARAGRAPH

PROBLEM

Fix these problems:

Don’t use bad shortcuts
Don’t use for example and etc. in the same context
Make a bullet list of the examples
Don’t use prior to

DISCUSSION

Bad Shortcuts

Don’t say this:

roles/responsibilities

Say this:

roles and responsibilities

Latin Phrases

Don’t say this:

etc.

Say this:

and so on

Never begin a string of items with e.g., which means for example, and end the string of items with etc., which means and so on. Use one or the other. To use them both is redundant.

Lists

Don’t say this:

Examples: Dual branding, logo presentation, copy text, field labels, font, button designs, color palette, background, etc.

Say this:

Pay close attention to the following:

- Dual branding
- Logo presentation
- Copy text
- Field labels
- Fonts
- Button designs
- Color palette
- Background

Usage

Don’t say this:

prior to

Say this:

before

REVISION

Before

Review branding and UX standards for onboarding to FakeCorp ID, including the approval process and supporting roles/responsibilities prior to going live. Examples: Dual branding, logo presentation, copy text, field labels, font, button designs, color palette, background, etc.

After

Review the branding and UX standards for onboarding to FakeCorp ID, including the approval process and supporting roles and responsibilities before going live.

Pay close attention to the following:

- Dual branding
- Logo presentation
- Copy text
- Field labels
- Fonts
- Button designs
- Color palette
- Background

Example 9

REWRITE THIS SENTENCE AS A LIST

PROBLEM

This long sentence (38 words) calls out three items. It presents some readability problems.

First of all, the sentence is too long. Break it up to open up more white space. Second, whenever you have a sentence with three or more items, you should consider converting it to a list.

DISCUSSION

The first two items are singular:

A page header
A value proposition

For clarity, you need to add the article A or the article The before the first two bullet items.

The third item is plural:

Value propositions above the marketing checkboxes and the legal terms-of-use checkboxes

The article The is optional for the plural items, but you might include The to ensure consistency.

REVISION

Before

These sections include a page header for all main FakeCorp ID UI pages, a value proposition on the create section of the login page, and value propositions above the marketing checkboxes and the legal terms-of-use checkboxes.

After

These sections include the following:

- A page header for all main FakeCorp ID UI pages
- A value proposition on the create section of the login page
- Value propositions above the marketing checkboxes and the legal terms-of-use checkboxes

These sections include the following:

- A page header for all main FakeCorp ID UI pages
- A value proposition on the create section of the login page
- The value propositions above the marketing checkboxes and the legal terms-of-use checkboxes

Example 10

REWRITE THIS BULLET LIST

PROBLEM

Wordiness!

To begin each bullet point with This page provides methods that handle is repetitious and is deadening on the ears.

You need to pare down the words in the list to the bare minimum. Cut out the words This page etc. in each bullet point and begin with the verb.

DISCUSSION

For example, don’t say this:

Event Management – This page provides methods that handle the setting or clearing of event notifications.

Say this:

Event Management – Sets or clears event notifications.

REVISION

Before

With an existing or newly-created test account, inspect any of the available API methods. The methods fall into these categories:

- Event Management – This page provides methods that handle the setting or clearing of event notifications.
- Initialization/Configuration – This page provides methods that handle the initialization or configuration of the FakeCorpID Web instance.
- Registration – This page provides methods that handle registration of a user’s username or password.
- Session Management – This page provides methods that handle session management.
- Account Recovery – This page provides methods that handle recovery of a user’s username or password.
- View/Edit User Info – This page provides methods that handle reviewing or editing user data.

After

With an existing or newly-created test account, inspect any of the available API methods. The methods fall into these categories:

- Event Management – Sets or clears event notifications.
- Initialization/Configuration – Initializes or configures the FakeCorpID Web instance.
- Registration – Registers a user’s username or password.
- Session Management – Handles session management.
- Account Recovery – Recovers a user’s username or password.
- View/Edit User Info – Reviews or edits user data.

Example 11

REWRITE THIS SENTENCE

PROBLEM

This long sentence from an environmental impact statement can be divided easily. Let me show you how.

DISCUSSION

The sentence makes two statements:

Residential development within the subarea would include medium‐density and high‐density housing options
[these options include] apartments, condominiums, townhouses, cottage housing, small‐lot detached single‐family housing, and conventional standard detached single‐family housing

Therefore, in your rewrite, write two sentences reflecting this division of content. Also, in your second sentence, create a list showing the different options in a more readable arrangement.

REVISION

Before

Residential development within the subarea would include medium‐density and high‐density housing options including apartments, condominiums, townhouses, cottage housing, small‐lot detached single‐ family housing, and conventional standard detached single‐family housing.

After

Residential development within the subarea would include medium‐density and high‐density housing options. These options include:

- Apartments
- Condominiums
- Townhouses
- Cottage housing
- Small‐lot detached single‐family housing
- Conventional standard detached single‐family housing