Write for a Global Audience

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.

Avoid Metaphorical Terms

A metaphor is a figure of speech in which a word or phrase that denotes one kind of object or action replaces 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.

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 with Care

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.

• Don't use jargon if the jargon obfuscates rather than clarifies the meaning.

• Use jargon if the jargon is essential to the technical meaning of the content.

• Consider explaining any jargon that you use if the audience isn't highly technical.

The following table lists some jargon typical of the tech industry and possible alternatives.

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 Non-Oppressive Language

The words you choose can have meanings separate from their dictionary definitions. To ignore that ignores the power of speech and writing. MongoDB wants to empower everyone to use our technology. Keeping with that goal, we must consider our use of terms identified as racist, sexist, or otherwise oppressive. Some terms lack any ambiguity.

The following table lists terms to avoid and some acceptable alternatives.

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