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

Example 1

REWRITE THIS SENTENCE

PROBLEM

Punctuation (comma fault)
Wordiness

DISCUSSION

Replace the comma fault with a period, and then start a new sentence.

Clean up the verbose language. Reduce the sentence to its bare essentials.

REVISION

Before

Visibility with respect to a resource has the same meaning as it does when applied to an API, see previous discussion on visibility for further details.

After

Visibility of a resource is the same as when you apply it to an API. See the previous discussion about visibility.

Example 2

REWRITE THESE SENTENCES

PROBLEM

Of our three example sentences, only the third sentence has incorrect punctuation.

The first and second example sentences each contain two short sentences apiece.

IMPORTANT: There is nothing wrong with having two sentences. This post intends to show you there is perhaps a more effective way to make your point by using a semicolon rather than having two complete sentences. It has to do with the close rhetorical relationship between sentence 1 and sentence 2.

DISCUSSION

When the first and second short sentences have a close rhetorical relationship, feel free to use a semicolon.

You may use a semicolon when you have these conditions:

The second short sentence is a contradiction of the first short sentence.
The second short sentence follows up the first short sentence with additional information.

NOTE: I cannot emphasize enough that these must be short independent clause linked by a semicolon. Do not do this with longer independent clauses. I’ll explain why in my next example.

Rule 1 – Use a semicolon to replace a period if you want to narrow the gap between two closely linked sentences.

Two complete sentences:

The refresh_expires_in property in validation responses causes refresh tokens to expire. The absence of this property indicates refresh tokens do not expire.

One sentence with a semicolon:

Refresh tokens expire if the validation response contains the refresh_expires_in property; they do not expire if the response does not contain the property.

Rule 2 – Use a semicolon before such words and terms as namely, however, therefore, that is, i.e., for example, e.g., for instance, etc., when they introduce a complete sentence.

Two complete sentences:

Some mailbox providers do not accept attachments. Others do not accept attachments over a certain size.

One sentence with a semicolon:

Some mailbox providers do not accept attachments; however, others do not accept attachments over a certain size.

Rule 3 – Use a semicolon to separate units of a series when one or more of the units contain commas.

Commas only:

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box, for a command line entry, and for an actual quotation.

Semicolons separate the three units in the sentence:

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box; for a command line entry; and for an actual quotation.

REVISION

Before

The refresh_expires_in property in validation responses causes refresh tokens to expire. The absence of this property indicates refresh tokens do not expire.

Some mailbox providers do not accept attachments. Others do not accept attachments over a certain size.

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box, for a command line entry, and for an actual quotation.

After

The refresh_expires_in property in validation responses causes refresh tokens to expire; the absence of this property indicates refresh tokens do not expire.

Some mailbox providers do not accept attachments; however, others do not accept attachments over a certain size.

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box; for a command line entry; and for an actual quotation.

Example 3

REWRITE THESE SENTENCES

PROBLEM

Too many semicolons.

DISCUSSION

Each example sentence shows you what I consider to be ill-advised usage of the semicolon. Readability is not a problem when you link short independent clauses with semicolons. However, in these examples, the long independent clauses make it difficult for the reader to track everything. Don’t put your reader to the test. The reader has enough challenges with the technology without wrestling with a series of long independent clause held together by semicolons.

When it comes to readability, some writing style experts say it makes no difference whether you end the sentence with a semicolon or a period. In fact, the Gunning Fog Index formula makes no distinction between sentences ending with periods and sentences ending with semicolons.

I disagree. In online documentation, it is much easier to see a period than it is to distinguish a semicolon from a colon. A period never gives the reader pause; a semicolon may cause the reader to pause if the type on the screen is not very large. Any unnecessary pause at all affects readability.

REVISIONS

Before

Most of the information you need for the service your business unit (BU) uses is in the following section for that service; however, this document also has a general discussion about Ways to Validate.

It’s important to understand that the security model for Operational VM is different from that of traditional FakeCorp hosting, and is more like that of Awesome Web Services; although the Operational VM Infrastructure team manages the security of the underlying environment, the zone creator or owner is responsible for managing security for all systems within their respective zones.

Using one solution, administrators can catalog, replicate, and duplicate backups; plus, they can streamline restores in a broad range of recovery scenarios.

You can enter interface range view to bulk configure multiple interfaces with the same feature instead of configuring them one by one; for example, you can perform the shutdown command in interface range view to shut down a range of interfaces.

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

Most of the information you need for the service your business unit (BU) uses is in the following section for that service. However, this document also has a general discussion about Ways to Validate.

It’s important to understand that the security model for Operational VM is different from that of traditional FakeCorp hosting, and is more like that of Awesome Web Services. Although the Operational VM Infrastructure team manages the security of the underlying environment, the zone creator or owner is responsible for managing security for all systems within their respective zones.

[rewrite 1] Using one solution, administrators can catalog, replicate, and duplicate backups. Also, they can streamline restores in a broad range of recovery scenarios.

[rewrite 2] Using one solution, administrators can catalog, replicate, and duplicate backups. In addition, they can streamline restores in a broad range of recovery scenarios.

You can enter interface range view to bulk configure multiple interfaces with the same feature instead of configuring them one by one. For example, you can perform the shutdown command in interface range view to shut down a range of interfaces.

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. To call delete user, the service needs to be granted the DELETE_USERS scope.

REMARKS

There are some authors who love to use semicolons to string together long independent clauses. While this practice may be grammatically correct, it is my view these authors sometimes are more interested in creating long, complicated sentences than in communicating basic information to the reader.

Long sentences—even the grammatically-correct ones—hurt readability. It’s that simple. Of course, there are always occasions when you need to write a long, complex sentence to communicate difficult conceptual information. But don’t go out of your way to write long sentences—just because you can.

Getting back to the semicolon: Use it sparingly if you must. Follow these rules:

Use a semicolon to replace a period if you want to narrow the gap between two closely linked short sentences.
Use a semicolon before such words and terms as namely, however, therefore, that is, i.e., for example, e.g., for instance, etc., when they introduce a complete short sentence.
Use a semicolon to separate units of a series when one or more of the units contain commas.

Example 4

REWRITE THIS SENTENCE

PROBLEM

In a series consisting of three or more elements, we separate the elements with commas. When a conjunction joins the last two elements in a series, use a comma before the coordinating conjunction (for example, and and or). This is called the series comma rule or serial comma rule.

Our problem sentence does not have the serial comma.

DISCUSSION

The serial comma is the commonly accepted practice in technical writing. Technical writing differs from journalism. Journalism generally follows AP style, which does not add a comma before the coordinating conjunction.

We need to add a comma after the word enforce to conform to the serial comma rule.

REVISION

Before

There are three policies: auto, enforce and none.

After

There are three policies: auto, enforce, and none.

Example 5

REWRITE THESE SENTENCES

PROBLEM

Each sentence has a misuse of quotation marks or an omission of quotation marks. Can you spot the discrepancies?

DISCUSSION

See the following “Revisions” section for the style explanations. The authority is the Microsoft Manual of Style.

REVISIONS

Before

Under “Database Name,” enter “ics.”

After

Under Database Name, enter ics.

Comment

Database Name is a user interface feature. Put UI features in bold type. Do not use quotation marks. For elements that the user must type exactly as the elements appear in the text, use bold. Therefore, ics is bold.

Before

To use the reports, pick your tenant from the drop-down menu, and click “Apply” in the lower right hand corner.

After

To use the reports, pick your tenant from the drop-down menu and click Apply in the lower right hand corner.

Comment

Apply is a UI feature. Put UI features in bold type. Do not use quotation marks.

Before

See Chapter 2, Content Formatting and Layout.

After

See Chapter 2, “Content Formatting and Layout.”

Comment

Chapter titles are title caps, in quotation marks. Don’t use italics.

Before

Enter “123456.”

After

Enter “123456″.

Comment

With a string, the quotation marks enclose the characters of the string. Therefore, in this example, the period falls outside the end quotation mark.

Before

He said, “We are ready to go”.

After

He said, “We are ready to go.”

Comment

For all other quotations (that is, quotations not involving characters in a string), the end quotation mark comes after the period.

Before

For Linux, run: dmesg | grep –I unknown partition

After

For Linux, run: dmesg | grep –I “unknown partition”

Comment

In a command line, put the selected command in quotation marks.

Example 6

REWRITE THESE SENTENCES

PROBLEM

Do not use an apostrophe to form a plural.

DISCUSSION

Use the apostrophe to form a contraction (it is becomes it’s; do not becomes don’t), or to indicate possession (my father’s car).

REVISIONS

Before

Versions of the dependent SDK’s can cause many headaches.

The SDK allows the client app to call our API’s directly to attempt a fake token refresh manually.

After

Versions of the dependent SDKs can cause many headaches.

The SDK allows the client app to call our APIs directly to attempt a fake token refresh manually.

Example 7

REWRITE THESE SENTENCES

PROBLEM

In formal documentation, never use the forward slash mark as punctuation. Follow the standard rules for punctuation.

DISCUSSION

Slash marks are sometimes allowed in the software development environment. The problem with this is sometimes unfiltered text from developer documentation eventually makes its way into documentation for the general public.

Therefore, it is best to avoid any use of the slash mark for punctuation. Don’t do it.

REVISIONS

Before

You would call this to paint the UI for any member who wants to update any of his/her information.

Identify the file/s at issue.

At grant time, the caller can request any/all/none of the client scopes.

This ensures we can trace back any messages prepared and/or sent to the exact sender and email list used to prepare/send them, no matter what future changes are made to those components.

After

You would call this to paint the UI for any member who wants to update any of his or her information.

Identify the file or files at issue.

At grant time, the caller can request any, all, or none of the client scopes.

This ensures we can trace back any messages we prepared and sent to the exact sender and email list used to prepare and send them, no matter what future changes are made to those components.

Example 8

REWRITE THESE SENTENCES

PROBLEM

Today, we are going to talk about the semicolon.

The first two example sentences contain errors. The last three are correct, but there are other correct ways to punctuate the sentences.

DISCUSSION

Here is our first example sentence:

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box, for a command line entry, and for an actual quotation.

The sentence itemizes three ways to use quotation marks:

For a specific string of characters to be entered somewhere on the UI, such as a text box
For a command line entry
For an actual quotation

The first bullet point contains the dependent clause such as a text box enclosed by commas. If it were not for that clause, you could separate the three items with commas. However, the clause enclosed by commas forces you to separate the three independent items with semicolons.

This is the correct punctuation:

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box; for a command line entry; and for an actual quotation.

Here is the second incorrect sentence:

I have one goal; to make the team.

A semicolon may be used between independent clauses. In our example, the text before the semicolon is an independent clause, but the text after the semicolon is a dependent clause. Therefore, you must use either a colon or a dash to separate the two clauses.

The final three example sentences are correct.

The third and fourth sentences have similar structures.

Call me tomorrow. You can give me an answer then.

My mother has shiny black hair. She loves to wash and comb it.

Both contain two independent clauses separated by periods. In each case, the information in the second sentence is closely linked to the information in the previous sentence. When that happens, it is perfectly OK to use a semicolon instead of a period.

Here is the final sentence:

The dash represents a pause in the sentence, which continues after the dash. However, capitalize the first word if the word is a proper name.

Whenever you see the words or abbreviations namely, however, therefore, that is, i.e., for example, e.g., for instance, etc., that is an indicator the information in the second sentence is closely related to the information in the previous sentence. Go ahead and use the semicolon. It’s OK.

REVISIONS

Before

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box, for a command line entry, and for an actual quotation.

I have one goal; to make the team.

Call me tomorrow. You can give me an answer then.

My mother has shiny black hair. She loves to wash and comb it.

The dash represents a pause in the sentence, which continues after the dash. However, capitalize the first word if the word is a proper name.

After

We use quotation marks for a specific string of characters to be entered somewhere on the UI, such as a text box; for a command line entry; and for an actual quotation.

I have one goal: to make the team.

I have one goal—to make the team.

Call me tomorrow; you can give me an answer then.

My mother has shiny black hair; she loves to wash and comb it.

The dash represents a pause in the sentence, which continues after the dash; however, capitalize the first word if the word is a proper name.

Example 9

REWRITE THIS SENTENCE

PROBLEM

We have four clauses separated by semicolons. The first three clauses are independent clauses, but the last clause is not an independent clause—it is a fragment.

DISCUSSION

The simplest and best solution is to take the original sentence and divide it into four simple sentences.

The first sentence seems to be incoherent:

The environment can be used to signify for what use the data services.

NOTE: See my rewrite for the first sentence. I think I am guessing correctly. After my technical writer review, the author reviews my changes. If I guess wrong, he or she gets to fix my mistake. I don’t have the last word on technical accuracy of the content.

In the second sentence, put a comma after typically.

Typically, this is something like DEV, QA, STAGE, PROD.

In the third sentence, the proper abbreviation for identification is ID, not id.

These help the application ID owner [to] know what environment the data is intended for.

The last sentence is a fragment:

Development, testing, production etc.

In the last sentence, there needs to be a comma between the word production and etc. Also, delete For example, and change etc. to and so on.

REVISION

Before

The environment can be used to signify for what use the data services; typically this is something like DEV, QA, STAGE, PROD; these help the application id owner know what environment the data is intended for; development, testing, production etc.

After

You can use the environment to signify how to use the data services. Typically, this is something like DEV, QA, STAGE, PROD. These help the application ID owner to know for which environment the data is intended. It might be for development, testing, production, and so on.

Example 10

REWRITE THESE SENTENCES

PROBLEM

Let’s talk about the comma.

All three sentences are what we call complex sentences. A complex sentence has an independent clause and at least one dependent clause. Each example sentence needs a comma to separate the independent clause from the dependent clause.

DISCUSSION

Sentence 1

These are the two clauses:

Dependent (that is, a fragment)—In this case
Independent (that is, a complete sentence with a subject and verb)—you should programmatically call the UpgradeNRT endpoint to initiate the NRT upgrade flow

Sentence 2

These are the two clauses:

Dependent—To start the onboarding process
Independent—see the Onboarding documentation

Sentence 3

These are the two clauses:

Independent—This ensures we can trace back any messages prepared or sent to the exact sender and email list used to prepare or send them
Dependent—no matter what future changes we make to those components

Rule

In a sentence containing both an independent clause and one or more dependent clauses, always separate the clauses with a comma. There is an exception to this rule, however. When you have a dependent clause that contains one or more commas already, use a semicolon to separate the respective clauses. We’ll cover that situation in a later example. Today, let’s focus our attention on using the comma as the separator.

REVISIONS

Before

In this case you should programmatically call the UpgradeNRT endpoint to initiate the NRT upgrade flow.

To start the onboarding process see the Onboarding documentation.

This ensures we can trace back any messages prepared or sent to the exact sender and email list used to prepare or send them no matter what future changes we make to those components.

After

In this case, you should programmatically call the UpgradeNRT endpoint to initiate the NRT upgrade flow.

To start the onboarding process, see the Onboarding documentation.

This ensures we can trace back any messages prepared or sent to the exact sender and email list used to prepare or send them, no matter what future changes we make to those components.

Example 11

REWRITE THIS SENTENCE

PROBLEM

This is a run-on sentence.

DISCUSSION

Divide this into two sentences:

It was a beautiful day.
There was not a cloud in the sky.

REVISION

Before

It was a beautiful day there was not a cloud in the sky.

After

It was a beautiful day. There was not a cloud in the sky.

Example 12

REWRITE THIS SENTENCE

PROBLEM

Add the serial comma.

DISCUSSION

The serial comma rule in technical writing is different from the rule in the AP Style Guide, which is used in journalism. AP rules do not require a comma after the penultimate item in a series.

REVISION

Before

Periodic reviews of cookbooks, roles and environments provide a clean and efficient automated deployment system.

After

Periodic reviews of cookbooks, roles, and environments provide a clean and efficient automated deployment system.

Example 13

COLON OR DASH?

Each one of the following sentences needs either a colon or a dash. Add the punctuation you think is correct:

PROBLEM

See the Discussion section for an explanation of the differences between colons and dashes.

DISCUSSION

When To Use a Colon

From Grammar Girl:

A colon informs readers that something more is coming along. The words after a colon define or clarify what came before the colon.

From the University of Puget Sound

A colon must follow a grammatically complete lead-in sentence or independent clause. What falls before the colon must make grammatical sense on its own.

From the website GrammarAbout:

Use a colon to set off a summary or a series after a complete main clause.

When To Use a Dash

From Penn State:

The dash … functions almost as a colon does in that it adds to the preceding material, but with extra emphasis.

From the

Words enclosed by a pair of dashes often provide an explanation or give parenthetical information. Using a pair of dashes instead of parentheses tends to emphasize (rather than de-emphasize) those words.

Comment

As a rule, the dash is more common and acceptable in less formal writing than it is in technical writing. I recommend using the dash in a bullet list of features, with the specifics of the bulleted feature following the dash. See the following Cookies section for a good example. Otherwise, avoid using the dash. Find a way to write around it.

CORRECT PUNCTUATION

Apathy

The reaction of the crowd signified only one thing: apathy.

The crowd clearly indicated their indifference to the provocative speech—an apathy that later came back to haunt them.

College Courses

The courses I am taking this semester are as follows: English, sociology, economics, political science, and psychology.

English, psychology, history, and philosophy—these were the classes I took last quarter.

What’s Your Name?

Remind me—what’s your name again?

Cookies

As part of the FakeCorpID login process, the following types of cookies are used:

- BLUE—A replacement for the GREEN cookie.
- RED—A RED cookie provides proof of authentication for an account in the EarthReg System.
- GREEN—A session-based cookie assigned to users that contains information such as the user’s e-mail address and tokens owned by the user.

Example 14

REWRITE THIS SENTENCE

PROBLEM

The sentence has two clauses. The first clause is a dependent clause (that is, a sentence fragment):

At a minimum in the JavaScript file

The second clause is an independent clause (that is, a complete sentence):

you must change the client ID and pointers to your responder page.

You must separate the two clauses with suitable punctuation. In this case, insert a comma after the word file.

DISCUSSION

See the Revision section for the rewrite.

REVISION

Before

At a minimum in the JavaScript file you must change the client ID and pointers to your responder page.

After

At a minimum in the JavaScript file, you must change the client ID and pointers to your responder page.

Example 15

REWRITE THIS SENTENCE

PROBLEM

Fix these problems:

Passive voice
Punctuation
Divide the sentence into two sentences

DISCUSSION

Passive Voice

Don’t say this:

The IDs of the content objects to be published are provided in a text file….

Say this:

A text file provides the IDs of the content objects to be published.

Punctuation

Do not use an apostrophe for a plural form. ID’s is incorrect.

When do you use an apostrophe? You use an apostrophe for a contraction (for example, don’t for do not). You use an apostrophe to indicate possession (for example, my father’s car).

Simple Sentences

Once you convert the sentence from passive voice to active voice, you can easily divide the example sentence into two simple sentences. There is no logical reason why the two independent clause must be connected by a conjunction. See the Revision section for the rewrite.

REVISION

Before

The ID’s of the content objects to be published are provided in a text file in the format of comma-separated values or with one value per line.

After

A text file provides the IDs of the content objects to be published. These IDs are formatted as comma-separated values or they have one value per line.

Example 16

REWRITE THIS SENTENCE

PROBLEM

This is run-on sentence. The comma after the word application is incorrect punctuation. This is called a comma splice.

DISCUSSION

See the Revision section for two different ways to rewrite the example sentence.

REVISION

Before

The access_token is valid for only a certain amount of time depending on the configuration of the clientID for your application, typically this is 24 hours.

After

The access_token is valid for only a certain amount of time, depending on the configuration of the clientID for your application. Typically, this is 24 hours.

Depending on the configuration of the clientID for your application, the access_token is valid for only a certain amount of time. Typically, this is 24 hours.

Example 17

REWRITE THIS SENTENCE

PROBLEM

The apostrophe in the word its.

DISCUSSION

We use an apostrophe for two reasons:

To form a contraction. For example, the subject it and the verb is are contracted to form the word it’s.
To indicate possession. For example, my father’s car.

Neither situation applies with our example sentence. Therefore, remove the apostrophe.

REVISION

Before

This specifies a unique digital asset by it’s digital asset source name.

After

This specifies a unique digital asset by its digital asset source name.

Example 18

REWRITE THIS SENTENCE

PROBLEM

These words are in quotation marks:

Database Name
ics

The author is using quotation marks incorrectly.

DISCUSSION

User Interface Features

When you talk about features on the user interface (UI), such as the label Database Name in the example sentence, do not enclose the label in quotation marks. Use boldface type.

Command Line and Text Box Entries

When you instruct the user to enter something in a text box or on a command line, do not use quotation marks. Use boldface type.

REVISION

Before

Under “Database Name,” enter “ics.”

After

Under Database Name, enter ics.

Example 19

REWRITE THESE SENTENCES

PROBLEM

Each example sentence begins with a dependent clause and concludes with an independent clause. These are the two dependent clauses:

Worried by the complaints

A dependent clause is a fragment, meaning it does not have a subject and verb.

DISCUSSION

You need to add commas to separate the dependent clauses from the independent clauses. See the Revision section.

REVISION

Before

No the shipment has not yet arrived.

Worried by the complaints we began an investigation.

After

No, the shipment has not yet arrived.

Worried by the complaints, we began an investigation.

Example 20

REWRITE THIS SENTENCE

PROBLEM

You should not use quotation marks for emphasis.

DISCUSSION

When you want to emphasize a word or phrase, use italics, not quotation marks.

REVISION

Before

Nexus is a third-party software solution that manages “artifacts” required for development.

After

Nexus is a third-party software solution that manages artifacts required for development.