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
Or
[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
1
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)
2
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)
3
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.
1
Don’t say this:
Inserts floating button bar
Say this:
Inserted floating button bar
2
This is OK:
Removed email support button from troubleshooting page
3
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
4
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
5
Don’t say this:
Auto open cloned object (configurable, off by default)
Say this:
Added auto open cloned object (configurable, off by default)
6
Don’t say this:
Ability to share saved searches
Say this:
Enabled the sharing of saved searches
7
Don’t say this:
Drag and drop to and from reference properties
Say this:
Added drag and drop to and from reference properties
8
Don’t say this:
Support for editing unmanaged external file properties
Say this:
Added support for editing unmanaged external file properties
9
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
10
This is OK:
Added typeahead to Editor field in search by user
11
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
12
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
13
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
14
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
15
This is OK:
Moved event search link to a tab under More search options
16
This is OK:
Renamed Cancel button to Close in the content edit form
17
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)
18
Don’t say this:
Maximize button in markup editor
Say this:
Added a maximize (+) button in the markup editor
19
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
20
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
21
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
Or
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