Punctuation

Ampersands

Don't use an ampersand (&) in text or headings to mean and unless you're referring to the symbol on the UI. In the following example, the button name on the UI includes an ampersand (&):

To continue, click Save & Go to Step 3.

Colons

Use the following guidelines for colons:

• Use a colon at the end of a sentence that introduces a list, table, figure, or example. If another sentence intervenes between the introduction and the thing being introduced, use a period instead of a colon.

• Use a colon at the end of the step to introduce substeps, a bullet list, or code that the user is expected to enter.

• In a list item, if you need to separate an initial term or phrase from the information that follows it, use a colon. For example:

  Public: This setting allows any two servers with public IP addresses to be load balanced. These can be nodes outside of the MongoDB network, but if they are, standard bandwidth rates apply.

• Don't use a colon at the end a table column header, a title, or a heading.

• Avoid using colons in sentences. You can almost always use two sentences instead. If you do use a colon in a sentence, however, don't capitalize the word that follows the colon unless the word is proper or is the beginning of a quotation.

• If a title or heading includes a colon, capitalize the first word that follows the colon, regardless of its part of speech.

• When you use a colon in a sentence, use lowercase for the first word that follows the colon unless it is a proper noun. When the colon introduces two or more sentences, a quotation, or question, capitalize the first word after the colon (from the Chicago Manual of Style 6.63, v17).

Commas

Use the following guidelines for commas. For basic comma usage, see section 6.16, Commas in the Chicago Manual of Style.

Dashes

An em dash is the longest dash. You can use em dashes to set off a long qualifier in the middle of a sentence if the use of commas would hinder readability. If you use em dashes for this purpose, don't use spaces around them. (For an example, see the second paragraph in the following section, "Ellipses.")

Don't capitalize the word following an em dash, unless the word is proper.

Don't use an em dash to separate a long sentence into two parts. Instead, create two sentences.

An en dash is longer than a hyphen and shorter than an em dash. Most often, you might use an en dash to show a range of numbers in a table or figure. For example, 10–20 diagrams.

Ellipses

Use an ellipsis (...) in syntax or to indicate omitted code in code examples.

Don't use an ellipsis in header text of table columns or when showing the name of an interface element—such as a text box, menu, menu command, or command button—even if the ellipsis is displayed on the interface. For example, don't use an ellipsis as follows:

• On the File menu, click Open....

• Do this ... (column header)

Exclamation points

Avoid using exclamation points.

Hyphens

This section provides general guidelines for hyphenation. For guidelines about using dashes, see Dashes.

• Hyphens in compound modifiers

• Hyphens with prefixes

Parentheses

Avoid parentheses in running text. Parenthetical text can distract the reader from the main idea of the sentence and disrupt the flow of the sentence. When possible, put parenthetical information in a separate sentence.

Following are some acceptable uses for parentheses:

• To define an abbreviation

• To show a special character

• To show examples

• To show a concise phrase that qualifies a term, title, or step

Don't add (s) or (es) to the end of a noun to indicate the possibility of more than one item. Use the singular form or the plural form, or use both forms joined by a conjunction.

Periods

Use the following guidelines for periods. For basic period usage, see a grammar reference, section 6.12, Periods in the Chicago Manual of Style.

• Use a period at the end of a declarative or imperative sentence, and insert only one space after the period.

• Place periods inside quotation marks, unless the quotation marks are part of a literal string. In such cases, place the period outside the quotation mark.

• Use periods in list items as follows:

  • If all of the items in a list are sentences, including imperative statements, end each item with a period.

  • If all of the items in a list are fragments, don't end the items with a period.

  • In a list of fragments, some or all of which are followed by sentences, end every fragment and sentence in the list with a period. For example, see the "Lists" topic.

• Use periods with abbreviations that could be misread as a word, such as in. (for inch).

• Precede a file name extension with a period. Also, assume that the period in a file name extension is pronounced as dot, and use the indefinite article a. For example, a .**ini** file.

• Don't end a title or a heading with a period.

Quotation marks

Refer to quotation marks as quotation marks, not as quote marks or quotes.

Use single and double quotation marks according to the following guidelines:

• Use quotation marks in user entries or syntax only if the software requires the quotation marks.

• Use quotation marks in message text only if the product shows quotation marks in the generated message. Use code font (monospace) to format messages.

• If you use a term in a unique or qualified sense, use double quotation marks in text only at its first occurrence, and omit the quotation marks in subsequent occurrences of the term. For example:

  The spelling checker "learns" the word. After it learns the word, the spelling checker ignores subsequent occurrences of the word in the document.

• Include appropriate punctuation, such as periods and commas, inside quotation marks unless the quotation marks are part of the syntax that the user must type.

• Don't use quotation marks for emphasis. Use italics instead, or other formatting as described in the "Text formatting" topic.

• Use quotation marks to enclose text that's used verbatim from another source, or to enclose quotations from people.

Semicolons

Avoid using semicolons, which are often misused and, even when used correctly, can make sentences longer and more difficult to understand.

• Instead of connecting independent clauses with a semicolon, break them into separate sentences.

• Instead of connecting more than two items with semicolons, create a list.

Slashes

Don't use a slash mark (/) to present a choice among, or a series of, actions or objects. Rewrite the phrase to eliminate the slash mark. Exceptions are established terms like client/server and read/write.

Don't use a slash in dates. For information about how to format dates, see Dates.