• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
  • Support Documentation

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
    • Prepositions
    • 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
    • Voice and tone
      • Voice and tone attributes
      • Best practices
  • 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
  • Control panel and portal standards
  • 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
    • July 18, 2019
    • March 12, 2019
    • March 6, 2019
    • March 1, 2019
    • 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

Quickstart#

Thank you for contributing to Rackspace content!

Don't worry if your job title doesn't include the word writer, information, or content—your most important contribution is your knowledge and expertise. Your willingness to share what you know with users will help them to accomplish their goals and be successful.

The Information Development team is ready to help turn your contributions into clear, concise, consistent, easy-to-read content for users. We do this, in part, by adhering to the standards that are defined in this style guide. The team doesn't expect contributors to know or adhere to all of these standards; however, if you are interested in improving your writing or learning some of the style standards at Rackspace, we invite you to explore them.

The style guide includes hundreds of standards, but you can start with the following ones to help you boost the effectiveness of your writing.

Standard More information and examples

Write in active voice.

Active voice makes the performer of the action (usually the user) the subject of the sentence. Active-voice sentences are more direct and easier to understand than passive-voice sentences.

Use active voice

Use present tense.

Users read content to help them perform tasks or to gather information. These activities occur in the users' present time, so the present tense is appropriate in most content.

Use present tense

Write to the user by using second person and imperative mood.

Users are more engaged with content when it talks to them directly. You talk to users directly by using second person, addressing the user as you. When you use second person with the imperative mood (in which the subject you is understood) and active voice, you make the text clear, concise, and direct.

Write to the user by using second person and imperative mood

Write short sentences and paragraphs, and use lists whenever possible.

Even a well-written long sentence can be hard to follow and understand, so try to limit sentences to 25 words. Short paragraphs are easier to scan and understand than longer ones. When listing three or more items, use a bullet list instead of embedding the items in a paragraph.

Write clear and concise sentences and paragraphs

Use action-oriented verbs.

Verbs carry the action in a sentence, and they make your content come alive for users. To make the biggest impact with your writing, use strong, simple, action verbs.

Use effective verbs

Write clear and brief step text.

When you write instructions for users, write short steps, number them, and use active voice and imperative mood.

Tasks

Clarify pronouns.

Pronouns such as it, this, there, and that are useful, but you must ensure that their antecedents (the words that they are used in place of) are clear, and that they (the pronouns) don’t cause vagueness and ambiguity.

Use pronouns carefully

Use correct punctuation.

Use periods to end most sentences, avoid quotation marks, and use serial commas.

Use correct punctuation

Punctuation

Use sentence-style capitalization for all titles and headings.

In sentence-style capitalization, you capitalize only the first word of the title or heading, plus any proper terms and terms that are always capitalized, such as some abbreviations.

Titles and headings

Write clear and consistent code examples.

When you create blocks of code as input or output examples, follow some basic guidelines to make them clear to users.

Code examples

Use consistent and simple terminology.

Use short, simple words, and use them as they are defined in a general or accepted industry dictionary. Each word or phrase should have only one meaning that is used consistently throughout the content. Avoid using humor, jargon, and metaphors.

Use consistent terminology

Terminology for a global audience

Concise terms

Previous Rackspace Style Guide for Technical Content
Next Writing guidelines
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
  • Technical Blog
  • Rackspace Blog
©2019 Rackspace US, Inc.
  • ©2019 Rackspace US, Inc.
  • About Rackspace
  • Investors
  • Careers
  • Privacy Statement
  • Website Terms
  • Trademarks