Use punctuation correctly and consistently. This section provides
guidelines for using punctuation in Rackspace documentation. For basic
rules about punctuation, see a grammar reference, such as the
Harbrace College Handbook.

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.

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

Guideline

Correct

Incorrect

In a series of three or more items, use a serial comma (that is, precede
the conjunction with a comma).

You can upgrade, migrate, and integrate the product.

You can upgrade, migrate and integrate the product.

Don't use only a comma to separate independent clauses. Doing so
creates a comma splice.

If you join independent clauses, insert a coordinating conjunction (such
as and) between them and precede the conjunction with a comma.

Click Options, and then click Allow Fast Saves.

CentOS 6 comes with Apache 2.2.3 and PHP 5.1.6, and you can install
them by using the default CentOS Package Manager, yum.

Click Options, then click Allow Fast Saves.

CentOS 6 comes with Apache 2.2.3 and PHP 5.1.6, you can install them
by using the default CentOS Package Manager, yum.

Use a comma to set off a nonrestrictive clause (one that begins with
which).

Don't use a comma to set off a restrictive clause (one that begins with
that).

The hourly backups are rolled into a nightly backup, which is retained
for two days. (nonrestrictive)

Enter the username and password that you just created. (restrictive)

The hourly backups are rolled into a nightly backup which is retained
for two days.

Enter the username and password, that you just created.

Use a comma to separate an introductory word, phrase, or clause from the
rest of the sentence.

When you check your email with an IMAP connection, you're accessing and
managing your email directly from the email server.

However, you can easily update the version by using the WordPress
management dashboard.

Unlike the other alarms in this list, you set the network check alarm
variable upon network check creation.

For more information, see Upgrading your Private Cloud.

When you check your email with an IMAP connection you're accessing and
managing your email directly from the email server.

However you can easily update the version by using the WordPress
management dashboard.

Unlike the other alarms in this list you set the network check alarm
variable upon network check creation.

For more information see Upgrading your Private Cloud.

Don't use a comma between the verbs in a compound predicate.

These open-source Python clients run on Linux or Mac OS X systems and
are easy to learn and use.

These open-source Python clients run on Linux or Mac OS X systems, and
are easy to learn and use.

When a comma is required after a quotation that's embedded in text,
place the comma inside the closing quotation mark.

In the section called "Parameters," enter the values for length, width,
and height.

In the section called "Parameters", enter the values for length, width,
and height.

Use commas in numbers with five or more digits. However, don't use
commas in the following types of numbers: addresses, fractional parts of
decimal numbers, page numbers, literal representations of user-entered
values or displayed values

Note: Don't use European-style numbering, which uses commas in the
place of periods. For example, use 3.14159, not 3,14159.

9001 N IH 35

1452.7532

page 1055

1024 bytes

9,001 N IH 35

1,452.753,2

page 1,055

1,024 bytes

When city and state names are embedded in a sentence, use a comma after
the city and the state.

The company headquarters were in Kansas City, Missouri, before the
merger.

The company headquarters were in Kansas City, Missouri before the
merger.

When a month, day, and year are embedded in a sentence, use a comma
before and after the year. When only the month and year compose the
date, omit the commas unless the syntax would ordinarily require a comma
following the year.

The company acquired a German subsidiary on July 15, 2009, and is
negotiating the purchase of a small Japanese company.

The publications plan was printed in November 2010 in Austin.

In December 2012, the database restoration failed.

The company acquired a German subsidiary on July 15, 2009 and is
negotiating the purchase of a small Japanese company.

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.

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:

When two or more words precede and modify a noun as a unit (also called
a compound modifier), use hyphens according to the following
guidelines.

To clarify meaning, use a hyphen. For example, high-level-language compiler
is clearer than high level language compiler.

Words that you hyphenate as compound modifiers preceding a noun might not be
hyphenated in other parts of a sentence or when used as another part of
speech. Hyphenate only if needed for clarity. For example,
local-level attributes but attributes defined at the local level.

Note: One exception is up-to-date, which is hyphenated in any position
in a sentence.

If the first component of a compound modifier is a number, use a hyphen. For
example, 32-bit operating system.

If the first word of a compound modifier is an adverb ending in -ly, don't
hyphenate the modifier. For example, fully qualified domain name.

If one of the elements of a compound modifier is a trademark, don't hyphenate
the modifier. For example, Java specific, not Java-specific.

Words with prefixes aren't usually hyphenated. However, a hyphen might
be necessary in the following cases:

You need to distinguish between homographs, such as re-create and
recreate.

The last letter of the prefix and the first letter of the root word
are the same. Exceptions are words such as reenter and
preemptive, which aren't likely to be misread.

The product team has hyphenated a term with a prefix, and you need to
follow suit in the docs for consistency with the interface—for
example, multi-factor authentication in the Identity product.
Whenever possible, work with the teams to use preferred spelling.

For the correct formatting of a specific word, see a dictionary or
Alphabetical list of terms. For more information about
hyphenating prefixes, see The Chicago Manual of Style.

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.

Examples

An access control list (ACL) allows access from an outside network into
the ObjectRocket system.

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.

Correct

Incorrect

You can choose Cloud Backups, Cloud Files, or both.

You can choose Cloud Backups and/or Cloud Files.
You can choose Cloud Backups/Files.

To access your computer, plug it in, log in to the operating system, and
type your password.