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

Terminology for a global audience#

Rackspace is a global company, with customers in many countries. A small amount of content has been translated, but most has not, which means that many customers who don't speak English as their first language consume our English content. All of the guidelines in this topic ("Basic writing guidelines") are designed to make content easy to understand for all audiences, but the following guidelines will especially clarify content for global audiences.

  • 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

Don't use idioms or colloquialisms#

An idiom is an expression whose meaning can't be derived from the literal meaning of the individual words. Some examples are in a nutshell, the bottom line, across the board, and on the fly.

A colloquialism is an expression considered more appropriate to familiar and casual conversation than to formal speech or to formal writing. Although we might like to establish a more conversational tone in some content, colloquialisms can be hard for non-native English speakers to understand.

Avoid idioms and colloquialisms as often as possible.

The following table lists some idioms and colloquialisms, and provides alternatives that you can use.

Idiom or colloquialism Alternative
for the most part generally
bear in mind, keep in mind consider, remember
keep an eye out for look for
figure out determine
stand for represent
come across encounter
fine tune refine, customize
get a feel for become familiar with
in light of because of
set aside defer, allocate
kind of like similar to
lots of many
what's more moreover
a hair smaller than slightly smaller than
when you're done when you're finished

Avoid metaphorical terms#

A metaphor is a figure of speech in which a word or phrase that denotes one kind of object or action is used in place of another to suggest a likeness or analogy between them. Although some common metaphors are easy even for people who don't speak English as a first language, avoid them as often as possible.

The following table provides some examples of metaphorical terms that can easily be replaced with one or more words.

Metaphor Alternative
a handful of companies a few companies
table a discussion postpone a discussion
the vanilla model the standard model
avoid common pitfalls avoid common problems
the drawback of frequent updates the disadvantage of frequent updates

Don't use humor#

Humor is culture specific. What might be funny in one culture might be offensive or obscene in another culture. Humor doesn't translate well, literally or figuratively, so don't use it.

Use jargon carefully#

Jargon is the specialized language of a profession. Jargon can be useful for technical audiences, but it can be meaningless to novice users and difficult to translate. Don't use jargon if you can easily and correctly use a more common or familiar term, or if the jargon obfuscates rather than clarifies the meaning. However, if the jargon is essential to the technical meaning of the content, use it. If the audience isn't highly technical, consider explaining any jargon that you use.

The following table lists some jargon typically used in the high tech industry and some possible alternatives.

Jargon Alternative Examples
abort (verb) stop, end, cancel If an error occurs during data entry, the update process stops.
boot, reboot (v) start, restart To apply your changes, restart the server.
bounce (v) restart Restart the service.
box (noun) computer, server The configuration specifies four servers.
cache (v) place in cache For quick access, you can place the command in cache.
debug (v) resolve After you resolve the problem, restart the server.
dropped (adj) discontinued In this release, support for Windows is discontinued.
execute (v) run Run the script.
fire, fire up (v) start After repairs are completed, you can start the server.
freeze (v) stop responding If the console stops responding, restart the application.
grayed, grayed out (adj) unavailable, dimmed You can't reduce the size of a Windows server, so options for smaller size servers are unavailable.
hang (v) stop responding A severe error might cause the server to stop responding.
interface (v) connect, communicate, interact Host 1 interacts with Host 2.
kill (v) stop, end, terminate You can terminate the process by pressing Ctrl+C.
launch (v) start Start the application monitor in debug mode.
machine (n) computer, server

If a UFO lands in the data center, the servers stop working.

Note: When referring to a virtual machine (VM), machine is correct.

ping (v) contact, alert To verify the connection, use the ping command to contact the other server.
sanity check (v) test, evaluate You can use a pre-existing function to evaluate the data that users enter.
slave (n, adj) subordinate, secondary (adj) Database replication that uses a master database server and a secondary (or slave) database server provides key advantages.
spin up (v) create If you need more capacity, create a new server.
throw (v) generate If the program fails, an error is generated.

Use culture-neutral language and examples#

Cultural references and examples in your documentation can cause problems for a global audience and for translation. Sounds, colors, animals, gestures, events, and symbols don't convey the same meaning in every culture.

  • Don't use the names of places, public figures, or holidays. If you must, use examples that represent a variety of cultures or that are internationally recognized. For example, use international cities, such as Paris, New York, Tokyo, London, and Hong Kong.
  • Don't use political, religious, ethnic, or historical references.
  • Don't use metaphors that are specific to one culture (for example, an American football metaphor).

Use generic examples that work in any target market.

If you create "named" users for extended examples or scenarios, use names that represent a variety of ethnic backgrounds, genders, and locations.

Use culture-neutral graphics#

Use graphics whenever possible to present processes and complex ideas. However, be aware of the following possible issues:

  • Some users don't typically read from left to right. If a graphics illustrates a sequence, make that sequence explicit by using numbers, arrows, or directional terms.
  • Don't rely on color alone to convey meaning. The color red, for example, has different meanings in different countries so could be interpreted differently by different users. Also, colors can have political or religious significance. Use neutral colors as often as possible.
  • Don't use a picture of a hand by itself (for example, a hand that is pointing). Almost every hand gesture is offensive to someone. A picture of a hand that is holding an item or interacting with something is generally acceptable.
  • Use generic or international images. Some examples are soccer players and equipment, generic landscapes, pens and pencils, and generic images of computer equipment. Avoid using images of men, women, flags, maps, animals, alcohol, trendy objects, historical references, or film, cartoon, or video characters.
Previous Avoid obscure non-English words and abbreviations
Next Alphabetical list of terms
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