IRC on Freenode #rackspace
  • Sign Up
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Email Admin Login
  • Rackspace Logo
  • Developer Home
  • Documentation & SDKs
  • Blog
SDK Quickstarts
  • Gophercloud Go
  • JClouds Java
  • OpenStack.NET.NET
  • pkgcloud Node.js
  • php-opencloud PHP
  • pyrax Python
  • fog Ruby
Cloud User Guides
  • Core Infrastructure
  • Cloud Servers
  • Cloud Images
  • Orchestration
Developer Community
  • Developer Blog
  • Knowledge Center
  • Developer Forum
  • Outreach & Events
Rackspace Cloud
  • Auto Scale
  • CDN
  • Cloud Block Storage
  • Cloud Databases
  • Cloud DNS
  • Cloud Files
  • Identity
  • Cloud Images
  • Cloud Load Balancers
  • Cloud Monitoring
  • Cloud Networks
  • Cloud Queues
  • Cloud Servers
  • Orchestration
Other Products
  • Airbrake
  • Mailgun
  • ObjectRocket
  • RedisToGo
Developer Community
  • Developer Blog
  • Knowledge Center
  • Developer Forum
  • Outreach & Events

Rackspace Developer Docs


Let’s Build Something Powerful Together!

Submit an issue
  • Rackspace Style Guide
  • Quickstart
  • Writing guidelines
    • Use active voice
    • Use present tense
    • Write to the user by using second person and imperative mood
    • Write clear and concise sentences and paragraphs
      • Use a consistent sentence structure
      • Restrict sentence length
      • Use only, but all of, the necessary words
      • Create short paragraphs
    • Use effective verbs
      • Use action-oriented verbs
      • Avoid nouns built from verbs
      • Use the simplest tense
      • Use helping verbs accurately
      • Use single-word verbs
      • Don't use verbs as nouns or adjectives
      • Don't use nonverbs as verbs
      • Use transitive verbs transitively, not intransitively
      • Don't humanize inanimate objects
    • Clarify gerunds and participles
    • Use that, which, and such as correctly
    • Use pronouns carefully
      • It
      • This
      • There
      • That
    • Use gender-neutral pronouns
    • Use positive statements
    • Use correct punctuation
    • Use interjections with care
  • Style guidelines
    • Abbreviations
      • Abbreviations of byte and bit
      • Common abbreviations
    • Capitalization
      • Capitalize proper nouns and adjectives
      • Capitalize most abbreviations
      • Capitalization in job titles
      • Capitalize team names
      • Capitalize UI labels as shown on the UI
      • Capitalize the names of product components as appropriate
      • Don't capitalize common nouns
      • Don't use all capitals for emphasis
      • Reference to other capitalization guidelines
    • Citations
    • Cloud account information
    • Code examples
      • Create a VM running a Docker host
      • Run the application
      • Remove the containers already using the port
      • Troubleshooting
    • Contractions
    • Copyrights
    • Dates
    • Email addresses
    • File types
    • Glossaries
      • Glossary terms
      • Glossary definitions
      • Cross-references to glossary terms
      • Guidelines for a comprehensive glossary
    • IP addresses
    • Keyboard keys
    • Links and cross-references
    • Lists
      • Introductory text
      • List items
    • Messages
    • Names
    • Notes and other notation types
    • Numbers
      • Numbers versus words
      • Commas in numbers
      • Ranges of numbers
      • Unspecified, generic, and unknown numbers
    • Parameters
    • Placeholder (variable) text
    • Plurals
    • Product names and version numbers
    • Punctuation
      • Ampersands
      • Colons
      • Commas
      • Dashes
      • Ellipses
      • Exclamation points
      • Hyphens
      • Parentheses
      • Periods
      • Quotation marks
      • Semicolons
      • Slashes
    • Symbols
    • Tables
      • Introductory text for tables
      • Table titles
      • Column headers
      • Table text
      • Table footnotes
      • Attribute or parameter tables in API documents
      • Examples
    • Tasks
      • Task titles
      • Task introductions
      • Prerequisites
      • Procedures
      • Steps
      • Results, verification, examples, and troubleshooting
      • Direction to the next action
      • Related topics
    • Telephone numbers
    • Text formatting
    • Time
      • 24-hour clock
      • 12-hour clock
    • Titles and headings
      • Capitalization
      • Style and structure
      • Text following titles and headings
      • Tables of contents
    • Trademarks
      • Examples of Rackspace trademarks
      • Examples of third-party trademarks
      • Links to company trademark pages
      • Trademark usage guidelines
    • URLs and domain names
  • Markup guidelines
    • ReStructured Text (RST)
    • MarkDown (MD)
  • Terminology guidelines
    • General terminology guidelines
      • Use consistent terminology
      • Use short, familiar words and phrases
      • Use consistent references to time, space, and versions
      • Avoid obscure non-English words and abbreviations
    • Terminology for a global audience
      • Don't use idioms or colloquialisms
      • Avoid metaphorical terms
      • Don't use humor
      • Use jargon carefully
      • Use culture-neutral language and examples
      • Use culture-neutral graphics
    • Alphabetical list of terms
    • Concise terms
    • Third-party names and trademarks
  • Screenshot and diagram guidelines
    • Screenshot guidelines and process
      • When to use screenshots
      • Screenshot alternatives
      • Before you create a screenshot
      • Screenshots in procedures
      • Screenshot checklist
    • Diagram guidelines
      • When to use diagrams
      • Before you create a diagram
      • Diagram checklist
  • How-To article guidelines
    • Use sentence-style capitalization for titles and headings
    • Use active voice
    • Use present tense
    • Write to the user by using second person and imperative mood
    • Write clear and consistent step text
    • Use consistent text formatting
    • Clarify pronouns such as it, this, there, and that
    • Clarify gerunds and participles
    • Write clear and consistent code examples
    • Use consistent terminology
    • When and when not to suggest contacting Support
  • Blog guidelines
    • Things to consider before writing a blog
    • Blog writing suggestions
    • Voice and tone
    • Write to the user by using second person and imperative mood
  • Error message guidelines
    • General guidelines
    • Message guidelines and examples
    • Message types
  • Release notes guidelines
    • Structure
    • Formatting
    • Wording
    • Editing existing release notes
  • User interface guidelines
  • Style guide revision history
    • February 22, 2019
    • February 6, 2019
    • January 21, 2019
    • January 4, 2019
    • November 5, 2018
    • November 2, 2018
    • September 25, 2018 (End of Q3 release)
    • June 29, 2018 (End of Q2 release)
    • May 8, 2018
    • April 16, 2018
    • June 19, 2017
    • April 28, 2017
    • November 10, 2016
    • July 27, 2016

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
  • Colons
  • Commas
  • Dashes
  • Ellipses
  • Exclamation points
  • Hyphens
  • Parentheses
  • Periods
  • Quotation marks
  • Semicolons
  • Slashes

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#

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

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.

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.
Previous Product names and version numbers
Next Symbols
Docs
  • Style Guide for Technical Content
  • Cloud Backup
  • Cloud Block Storage
  • Cloud Databases
  • Cloud DNS
  • Cloud Files
  • Identity
  • Cloud Images
  • Cloud Load Balancers
  • Cloud Monitoring
  • Cloud Orchestration
  • Cloud Networks
  • Cloud Queues
  • Cloud Servers
  • Rackspace Auto Scale
  • Rackspace CDN
Sdks
  • Go
  • Java
  • .Net
  • Node
  • PHP
  • Python
  • Ruby
Partner Tools
  • Airbrake
  • Mailgun
  • ObjectRocket
  • RedisToGo
Blog
  • Developer Blog
©2018 Rackspace US, Inc.
  • ©2018 Rackspace US, Inc.
  • About Rackspace
  • Investors
  • Careers
  • Privacy Statement
  • Website Terms
  • Trademarks