Chapter 2. Punctuation

Follow these guidelines to apply correct and consistent punctuation.

For more information about punctuation, see Developing Quality Technical Information, Chapter 7, “Use consistent and appropriate punctuation.”

Punctuation marks and special characters

Ensure that references in text to punctuation marks and special characters are clear. Special characters include symbols such as the ampersand (&) and the at sign (@).

Some punctuation marks and special characters are known by different English names in different geographic areas. For example, the number sign (#) is commonly referred to as the pound sign in the US and the hash sign in the UK. Use the names that are listed in the table in this topic.

Individual punctuation marks or special characters

Follow these guidelines for individual punctuation marks or special characters:

• Do not refer to an individual punctuation mark or special character by its symbol alone. Use the name alone, or use the name followed by the symbol in parentheses. Use the name alone if the punctuation mark or special character is standard, such as a comma or period, and including the symbol would clutter the text. Include the symbol in parentheses when a punctuation mark or special character is not well known or when including the symbol improves clarity.

• If you refer to the punctuation mark or special character again close to the first occurrence, you can either repeat the name without the symbol in parentheses or refer to the punctuation mark or special character generically.

• Do not use symbols instead of words in running text.

• When you write about a user interface, do not include a punctuation mark, such as a colon or ellipsis, that is part of an interface element label unless one of the following conditions applies:

• The omission of the punctuation mark causes confusion.

• You use a tool that extracts the wording from the label, including any punctuation, for use in the documentation.

Series of punctuation marks or special characters

Follow these guidelines for a series of punctuation marks or special characters:

• Introduce the series with a complete sentence that ends with a colon.

• Place the series of symbols on the following line.

• To ensure that readers clearly interpret the items in the series, follow these guidelines:

• Do not enclose the series in parentheses.

• Do not separate the items with punctuation marks, such as commas.

• Do not include coordinating conjunctions, such as and, between the items.

• Do not punctuate the series with a final period. If the series includes a period, avoid placing it at the end of the series.

• Do not in clude the names of the punctuation marks or special characters.

• Avoid using characters that are not supported in most standard code pages, especially in online information that is translated. In addition to standard punctuation marks, most code pages support the following special characters:

! # $ % & * + / < > @ ^ ~

• To sort punctuation marks and special characters, use the following ASCII sort sequence unless you use a tool that imposes a different sort sequence:

(space) ! “ # $ % & ’ ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` } | { ~ ¢ > ≤ ÷ °

Common punctuation marks and special characters

Use the names in the following table to refer to punctuation marks and special characters.

Apostrophes

Use an apostrophe in only some plural and possessive forms.

Apostrophes in plurals

Most plural forms do not require an apostrophe. For example, form the plural of words, abbreviations, and numbers by adding the letter s alone.

Use an apostrophe and the letter s (’s) to form the plural of single letters.

Apostrophes in possessives

Follow these guidelines for using apostrophes in possessives:

• In general, use ’s to show the possessive form of people.

• Avoid using ’s to show the possessive form of inanimate objects. Make the possessive noun an adjective, or use the possessive noun in a prepositional phrase.

• Do not use ’s to show the possessive form of abbreviations, brand names, or product names.

• Do not use ’s to show the possessive form of IBM unless you refer to only the company and do not identify goods or services.

Colons

Use a colon to indicate that closely related information follows.

Colons in running text

Follow these guidelines for using colons in running text:

• Use a colon after an independent clause to introduce an inline list.

• Use a colon after the label of a note.

• Use a colon between two independent clauses to amplify, elaborate on, or show a close relationship to the first clause.

• Do not insert a space before a colon, and insert one space after.

Colons in headings and titles

Do not use a colon at the end of a heading or title.

Use a colon between a heading and subheading or between a title and subtitle. Do not insert a space before the colon, and insert one space after the colon. Capitalize the first letter of the subheading or subtitle.

Colons after introductory text

Use a colon after the introduction to a vertical list, including a procedure or substeps in a procedure. To avoid translation problems, make the introduction a complete sentence. If a sentence intervenes between the introduction and the first item, use a period after both the introduction and the intervening sentence. For more information about introducing lists and procedures, see “Lists” on page 75 and see “Procedures” on page 84.

Use a colon or a period after the introduction to a figure or table. For more information about introducing figures and tables, see “Figures” on page 90 and see “Tables” on page 96.

Colons and capitalization

In general, use a lowercase letter on the text that immediately follows a colon.

Use an uppercase letter on the text that immediately follows a colon when the text is one of the following items:

• Item in a vertical list

• Note that follows a label

• Proper noun

• Quotation

• Subheading on the same line as a heading

Colons with numbers

Use colons to separate units of time. Do not insert a space before or after the colon.

Use colons to express ratios. Do not insert a space before or after the colon.

Commas

Use a comma to separate elements in a sentence, such as items in a series, clauses, or introductory phrases. If a sentence is complex or longer than 25 words, consider rewriting it, separating it into multiple sentences, or presenting its contents in a vertical list.

Commas between clauses

Use a comma between independent clauses that are separated by a coordinating conjunction unless the clauses are short or closely related. Coordinating conjunctions are and, but, or, nor, for, so, and yet.

Then is not a coordinating conjunction. You cannot join independent clauses with then unless you add a semicolon or a coordinating conjunction.

Do not use a comma between an independent clause and a dependent clause that are separated by a coordinating conjunction unless the sentence might be misread without a comma.

Commas after introductory words and phrases

Use a comma after most introductory words, clauses, and phrases.

Commas between items in a series

Use commas to separate items in a series of three or more. Use a comma before the conjunction that precedes the final item.

Exception for marketing content: In marketing content, use a comma before a conjunction only for clarity. For details and examples, see “Exceptions for marketing content” on page 274.

Do not add commas or conjunctions between the items in a series of special characters.

Commas with nonrestrictive clauses

Always use a comma before a nonrestrictive clause, which begins with the word which. Do not use a comma before a restrictive clause, which begins with the word that.

For more information about using commas with nonrestrictive clauses, see Developing Quality Technical Information, Chapter 7, “Correct pronoun problems.”

Commas as separators in numbers

Specific rules apply to using commas as separators in numbers based on the length of the numbers and how they are used in a sentence. For details about using commas as separators in numbers, see “Separators in numbers” on page 159.

Commas with quotation marks

In most cases, place commas inside closing quotation marks. For details about using commas with quotation marks, see “Quotation marks with other punctuation” on page 66.

Dashes

Do not use en dashes or em dashes in technical information.

En dashes

The en dash (–) derives its name from typesetting: the length of an en dash is the width of an uppercase N in the same font. En dashes are longer than hyphens (-) and shorter than em dashes (—). Most keyboards do not have a key for an en dash.

Do not use en dashes; use hyphens instead.

Em dashes

The em dash also derives its name from typesetting: the length of an em dash is the width of an uppercase M in the same font. Em dashes are longer than both hyphens and en dashes. Most keyboards do not have a key for an em dash, but many authoring tools provide a symbol for an em dash, and some authoring tools create an em dash if you type two hyphens together.

Do not use em dashes in technical information. More common punctuation marks, such as commas, parentheses, or a colon, provide the same result. Rewrite the text or use different punctuation.

Exception for marketing content: Em dashes are acceptable in marketing content. For details and examples, see “Exceptions for marketing content” on page 274.

Ellipses

Avoid using ellipses in running text. If you use an ellipsis, apply the correct spacing.

Ellipses in running text

Usually, an ellipsis in text indicates a pause or an omission. Avoid using ellipses in technical information because the omission can be unclear and because ellipses can contribute to an overly informal tone. In general, include information that is important and eliminate information that is not.

Exception for marketing content: An ellipsis to show a pause is acceptable in some marketing content. For details and examples, see “Exceptions for marketing content” on page 274.

Ellipses in examples and quotations

You can use an ellipsis in an example or quotation if you can convey the information without presenting the entire text. However, do not use ellipses at the beginning or end of a direct quotation; start and end quotations with words, even when the text is truncated.

Ellipses in user interfaces

Usually, an ellipsis in a user interface element indicates that more user input is required to complete an action. When you write about a user interface, do not include ellipses that are part of an interface element label unless one of the following conditions applies:

• The omission of the ellipsis causes confusion.

• You use a tool that extracts the wording from the label, including any punctuation, for use in the documentation.

Spacing and punctuation with ellipses

For ellipses in user interfaces, apply the spacing that the interface design guidelines for the product specify, or be consistent with existing instances in the interface.

For ellipses in text, some authoring tools provide an ellipsis symbol with default spacing between the periods. If you do not use a symbol and you type an ellipsis, do not insert spaces between the periods in the ellipsis.

For both ellipsis symbols and typed ellipses in text, follow these spacing guidelines:

• Insert one space before the ellipsis.

• Insert one space after the ellipsis, unless a punctuation mark follows the ellipsis. In that case, do not insert a space between them.

• Keep all the periods in an ellipsis together on one line.

Exclamation points

Do not punctuate sentences with exclamation points because their tone can be interpreted negatively, for example, as aggressive, condescending, or overly informal.

Convey urgency or emphasis with the appropriate words, not with exclamation points. To call attention to important hints, tips, guidance, restrictions, or advice that might be overlooked, consider using a note that has a meaningful label.

For more information about tone, see Developing Quality Technical Information, Chapter 7, “Write with the appropriate tone.”

Hyphens

Use hyphens to increase clarity by connecting related information. For example, use hyphens in compound adjectives to show which words modify another word, and use hyphens with numbers to show how they relate to measurements, words, or other numbers.

Hyphens with prefixes and suffixes

In most cases, do not use a hyphen to connect a prefix or suffix to a word. Typically, a hyphen is unnecessary if a reader can read the word accurately without a hyphen.

To determine whether to hyphenate a prefix, consult Merriam-Webster’s Collegiate Dictionary. If the dictionary does not contain a word or provide a precedent, follow the guidelines for hyphenating prefixes in The Chicago Manual of Style. Both references favor a closed style for prefixes, which omits the hyphen when possible.

Generally, hyphenate a prefix only to prevent misreading or ambiguity. Specifically, hyphenate a prefix in the following situations:

• When Merriam-Webster uses a hyphen (for example, bi-level, co-edition)

• When you must distinguish the word from a homonym (for example, co-op, re-cover, re-create, re-sign)

• When the root word is capitalized or a numeral (for example, pre-2000)

• When the root word consists of more than one word (for example, non-English-speaking citizens, pre-latency-period transaction)

• In some words in which identical letters would be next to each other (for example, anti-intellectual, bell-like, co-opt, de-emphasize)

• When the prefix is self-, all-, or ex- (meaning formerly)

The following table lists common prefixes and examples of when to omit or use a hyphen:

Hyphens with compound words

To clarify which noun is being modified, avoid long compound phrases and noun strings, and use hyphens where appropriate. Consider using a prepositional phrase after a noun instead of a compound adjective.

For more information about avoiding noun strings, see Developing Quality Technical Information, Chapter 5, “Avoid long strings of nouns.”

When you write compound phrases, use hyphens to avoid ambiguity, but do not use hyphens unnecessarily. Follow these guidelines:

• Hyphenate compound adjectives and adverbs before a noun if readers might misinterpret the term or phrase.

• Do not use a hyphen after an adverb or adjective that ends in -ly because such terms are never ambiguous.

• In most cases, when a compound adjective follows a noun, do not hyphenate it. In some cases, a hyphen is necessary to avoid ambiguity.

• Hyphenate all the words that function as the compound adjective before the noun.

• Hyphenate the prefix to a hyphenated compound.

• When hyphenated compounds in a series have the same first word or last word, repeat the common word. Omitting words makes translation more difficult and slows comprehension.

Hyphens and capitalization

Apply the following capitalization guidelines to hyphenated words:

• When a hyphenated word occurs at the beginning of a sentence, capitalize only the first element in the word unless a subsequent element is a proper noun or proper adjective.

• When a hyphenated word occurs at the beginning of a heading with sentence-style capitalization, capitalize only the first element in the word unless a subsequent element is a proper noun or proper adjective.

• When a hyphenated word occurs in a heading with headline-style capitalization, capitalize the first element in the word; the last element in the word, regardless of its part of speech; and any element that is not an article, preposition, or coordinating conjunction.

Hyphens with numbers

Use hyphens in some spelled-out numbers and in some number compounds. For details about using hyphens with numbers, see “Expressing numbers” on page 155.

Hyphens with ranges

Follow these guidelines for using hyphens with ranges:

• Use a hyphen to show a range of items, such as numbers, letters, pages, dates, or codes. Insert a space before and after the hyphen.

• Do not use words such as from or between to show a range; it is not clear whether the items are the boundaries of the range or are included in the range.

• If a number range is part of a compound adjective, hyphenate only the number and unit. You can omit the unit from the first compound in a number range.

For details about how to show a range of measurements, see “Ranges of numbers” on page 159.

Parentheses

Use parentheses to identify items such as abbreviations, symbols, and measurements, but avoid using parentheses in running text.

Parentheses with abbreviations, symbols, and measurements

If you write out the name of an abbreviation, punctuation mark, or special character, enclose the abbreviation, mark, or character in parentheses following the text. If you provide a measurement, you can include an equivalent value from an alternative system in parentheses following the measurement.

Parentheses to form plurals

Do not use the letter s in parentheses (s) to indicate that a noun can be singular or plural. Some languages form plural nouns differently than English, and the construction (s) can cause translation problems. Instead, use the plural form or, if it is important to indicate both singular and plural options, use the phrase one or more.

Parentheses in running text

Avoid using parentheses in running text because text in parentheses is decreased in importance. In general, include information that is important and eliminate information that is not. Parentheses can also interrupt the flow of a sentence. Try to rewrite the text or use other punctuation instead of parentheses. If you must write a sentence that includes text in parentheses, ensure that the sentence is grammatically correct and technically accurate if you omit the parenthetical text.

If the parenthetical text is not a complete sentence, include the parenthetical text in the sentence to which it pertains. Do not use an initial uppercase letter on the first word unless it is otherwise required, and do not insert a period inside the parentheses.

If the parenthetical text is a complete sentence, you can either include the parenthetical sentence in the sentence to which it pertains or you can enclose it in parentheses as a separate sentence. If you include the parenthetical sentence in the sentence to which it pertains, do not use an initial uppercase letter on the first word, and do not insert a period inside the parentheses. If the parenthetical text is a separate sentence, use an initial uppercase letter on the first word, and insert the period inside the parentheses.

Periods

Use periods correctly.

Periods in running text

Use a period at the end of a sentence. After a period, use the spacing that your authoring tool provides. If you insert spacing manually, insert only one space after a period.

Periods with abbreviations

Follow these guidelines for using periods in abbreviations:

• Omit periods in uppercase abbreviations.

• Include periods in lowercase abbreviations that relate to time or that can be confused with words.

• Omit periods in abbreviations for units of measure, unless they can be confused with words.

• Omit periods in abbreviations for academic degrees.

• Include periods in abbreviations for social titles.

• If an abbreviation that requires a period occurs at the end of a sentence, do not include another period.

Periods with file name extensions

Include a period before a file name extension. Assume that the period in a file name extension, such as .exe, is pronounced as dot, and use the indefinite article a.

Periods in headings and titles

Do not end a heading with a period.

In books, use a period in titles for chapters and appendixes. Insert the period after the name of the entity and the identifying number or letter and before the descriptive name.

Periods after introductory text

Use a period or a colon after the introduction to a figure or table. For more information about introducing figures and tables, see “Figures” on page 90 and see “Tables” on page 96.

Use a period after the introduction to a vertical list, including a procedure or substeps in a procedure, when a sentence intervenes between the introduction and the first item. For more information about introducing lists and procedures, see “Lists” on page 75 and see “Procedures” on page 84.

Periods with lists

Write lists so that all or none of the items start with complete sentences. If list items comprise only complete sentences, include a period after each sentence.

If list items comprise only sentence fragments, do not include any end punctuation.

If a list contains list items that start with sentence fragments, and one or more of the fragments are followed by complete sentences, include periods after all sentence fragments and sentences.

Periods with numbers

Use a period on the line (.), not a raised dot (·), as a decimal separator unless the comma (,) is a legal requirement in the particular country for which you are writing.

Periods with parentheses

If the parenthetical text is not a complete sentence, do not insert a period inside the parentheses.

If the parenthetical text is a complete sentence, you can either include the parenthetical sentence in the sentence to which it pertains or in parentheses as a separate sentence. If you include the parenthetical sentence in the sentence to which it pertains, do not insert a period inside the parentheses. If the parenthetical text is a separate sentence, insert the period inside the parentheses.

Periods with quotation marks

In most cases, place periods inside closing quotation marks. For details about using periods with quotation marks, see “Quotation marks with other punctuation” on page 66.

Quotation marks

Use double quotation marks (”) and single quotation marks (’) correctly.

Terminology for quotation marks

The term quotation mark refers generically to a double quotation mark character or a single quotation mark character. When you refer to quotation marks in text, specify whether you mean double quotation marks or single quotation marks.

To refer to the position of the characters, use the terms opening and closing.

Do not use the term quotes to refer to quotation marks or to the text between quotation marks. Use the term quote only as a verb, and use quotation as the noun.

Quotation marks for emphasis

Do not use quotation marks to emphasize words or phrases. Quotation marks can clutter the text. To emphasize words as words, use italic font. To call attention to information that might be overlooked, consider using a note that has a meaningful label.

Double quotation marks

Use double quotation marks for the following items:

• Quotations

• Words that are used in a special sense

Use double quotation marks for a word that is used in a special sense only if no other word clearly expresses the meaning. Do not overuse quotation marks for this purpose. Using a word in a special sense can cause problems for translation.

• References to topic titles, section titles, chapter titles, or online information

• Names of these items, when they have sentence-style capitalization:

• Notebooks

• Pages

• Panes

• Portals

• Portlets

• Windows

• Wizards

Single quotation marks

Use single quotation marks for the following items:

• Quotation marks inside double quotation marks

• Code examples, code syntax, and programming elements that require single quotation marks

• Hexadecimal numbers

Quotation marks with other punctuation

In most cases, place commas and periods inside closing quotation marks, and place other punctuation marks outside.

Unless a punctuation mark is part of the syntax, do not place a punctuation mark inside the quotation marks of these items:

• Coding statements

• Symbolic names

• Hexadecimal, binary, or octal values

• Other programming elements that use quotation marks

When possible, rewrite the text to move the comma away from the quotation marks of these items.

Typographical considerations for quotation marks

You can generate quotation marks directly through the keyboard or by using tagging in an authoring tool. Use the correct characters for the context and be consistent.

Some contexts require these typographic characters:

• Opening quotation mark (‘): Unicode X'2018'

• Closing quotation mark (’): Unicode X'2019'

• Opening quotation marks (“): Unicode X'201C'

• Closing quotation marks (”): Unicode X'201D'

Other contexts require straight keyboard characters:

• Straight single quotation mark ('): Unicode X'0027'

• Straight double quotation marks ("): Unicode X'0022'

For example, always use keyboard characters for code examples, code syntax, and hexadecimal numbers that use the format X'nn'.

If you use typographic characters in an authoring tool, they might not transfer well to other tools or programs. In many cases, it is safer to consistently use straight keyboard characters.

Semicolons

Use a semicolon to separate independent clauses or items in a series that has internal punctuation. If a sentence is complex, difficult to read, or longer than 25 words, consider rewriting it, separating it into multiple sentences, or presenting its contents in a vertical list.

Semicolons between independent clauses

Use a semicolon between independent clauses that are not connected by a coordinating conjunction. Coordinating conjunctions are and, but, or, nor, for, so, and yet. Use a coordinating conjunction when you need to show the relationship between clauses; use a semicolon when the relationship between clauses is clear.

Use a semicolon between independent clauses that are connected by a conjunctive adverb or a transitional phrase. Conjunctive adverbs include also, besides, consequently, conversely, finally, however, instead, likewise, next, otherwise, similarly, specifically, still, subsequently, then, and therefore. Transitional phrases include at the same time, for example, in addition, and on the contrary.

Semicolons between items in a series

Use a semicolon between items in a series that has internal punctuation.

For more information about misusing semicolons, see Developing Quality Technical Information, Chapter 7, “Check for sentence fragments.”

Slashes

Avoid using forward slashes (/) and backslashes () in most text and in dates.

Slashes in running text

Follow these guidelines for using slashes in running text:

• In most cases, do not use slashes in text because they can be ambiguous. For example, 1/2 can mean one half, one and two, one of two, and one or two. Rewrite the text using and, of, or or.

• Do not use the construction and/or, which can cause confusion and problems for translation. Instead, clarify the options by using and or or, or by stating the choices, such as option A, option B, or both.

For more information about writing for translation, see Developing Quality Technical Information, Chapter 11, “Applying quality characteristics to information for an international audience.”

• In a few cases, use a forward slash between words when the slash construction is an industry standard.

• Do not insert a space before or after a forward slash or backslash.

Slashes in dates

Do not use slashes in dates. For guidelines on how to express dates, see “Dates” on page 178.

Slashes in fractions

Whenever possible, use decimal numerals instead of fractions to represent fractional parts of units.

Slashes in mathematical equations

Use a forward slash (/) as an operational symbol for division. Do not insert a space before or after the forward slash.

Slashes in path names

When you refer to a subdirectory by using a full path name, such as /usr/bin/samples, use a forward slash (/) or backslash () according to the convention of the operating system. For information that applies to multiple operating systems, be consistent and describe the convention if necessary.

If a path does not fit on one line, end the first line after an existing forward slash or backslash, and continue the path on the next line. Do not add a hyphen to indicate a break in a path.

Slashes in web addresses

Follow these guidelines for using slashes in web addresses:

• If the protocol of a web address is HTTP, you can typically omit the protocol, colon, and forward slashes (http://); most browsers default to an HTTP connection. However, some tools convert addresses into live links and require the full address, including http://. If the protocol is not HTTP, include the protocol in the web address.

• Do not include a forward slash at the end of a web address.

• If a web address does not fit on one line, end the first line after an existing forward slash (/) or double forward slash (//), and continue the address on the next line. Do not add a hyphen to indicate a break in a web address.