Developer Docs


Let’s Build Something Powerful Together!

Submit an issue

Punctuation#

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.

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.

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.

The publications plan was printed in November, 2010, in Austin.

In December 2012 the database restoration failed.

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#

Ellipses is the plural of ellipsis. An ellipsis is made up of three contiguous periods. (Technically, the dots in an ellipsis are ellipsis points, but for our purposes, you can think of them as periods.) Ellipses indicate the omission of part of a sentence, paragraph, or larger block of text or code examples where the omission is not pertinent to the understanding of the subject at hand.

Suspension points#

When you use ellipses to indicate hesitation, they are called suspension points. Don't use ellipses this way in our documentation.

Example:

Not recommended: The answer is ... wait for it ... that you shouldn't do this.

How to use ellipses#

In a user interface

When ellipses appear in a user interface (a text box, menu, menu command, or command button), exclude them from the documentation describing the user interface (even if the ellipsis is displayed on the interface) unless their omission could cause confusion. For example, if the text on the button in the UI reads "Save ...", document it as "click Save".

In text

Don't use ellipses in your written documentation. Omit any unnecessary information and include all necessary information.

Don't use an ellipsis in header text of table columns.

However, it's acceptable to use ellipses in quoted text (to replace a portion of the quoted text) except when they appear at the beginning or end of the text.

Examples:

Not recommended: My high school English teacher made me learn that Shakespeare quote about all the world being a stage and " ... all the men and women merely players."

Not recommended: My high school English teacher made me learn that Shakespeare quote: "All the world's a stage, And all the men and women merely players ...."

Note that the previous example ended with four ellipsis points. The final ellipsis point is, in fact, a period. So when the material that you're omitting contains one or more sentence boundaries, use four dots instead of three.

Example:

Recommended: My high school English teacher made me learn that Shakespeare quote: "All the world's a stage, ... And one man in his time plays many parts."

Punctuation and spacing#

Keep all three ellipsis points together. When creating an ellipsis, instead of the ellipsis character use three periods in a row. Insert one space before and after the ellipsis unless a punctuation mark immediately follows the ellipsis. In this case, don't insert a space after the ellipsis.

Examples:

Not recommended: You don't need to understand all the other Python code in there...we'll explain it all in class.

Recommended: You don't need to understand all the other Python code in there ... we'll explain it all in class.

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#

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.

Hyphens with prefixes#

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.

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.

Examples

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

Object names can't contain characters such as dollar signs ($) and question marks (?).

DNS is analogous to a phone book in that it assigns a numerical identifier (for example, 210.48.108.35) to a particular name (for example, www.diversity.net.nz).

4. (Optional) Enter first and last name information for the mailbox owner.

You can submit up to 10 messages (the default) in a single request.

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.

  • For information about how to use quotation marks with citations, see Citations.

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.

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. To access your computer, plug in the computer/log on/type your password.