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.

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.

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.

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.

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 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.