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 Rackspace 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.

Commas#

Use the following guidelines for commas. For basic comma usage, see a grammar reference, such as the Harbrace College Handbook.

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.

Note: To show a range of numbers in text, use to or through instead of an en dash.

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, such as the Harbrace College Handbook.

• 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.