global-001 should GuidesAPI docsMarketing Write for a global audience. Avoid cultural assumptions, idioms, and language that may be hard to understand or translate.
Globalization
Globalization makes documentation usable across countries, cultures, and languages. Use this page when you choose examples, references, sentence structures, or terms for content that may be translated.
Many globalization rules overlap with other topics, such as clarity and precision, so see the applicable rules from other topics at the end of this page. For guidance about formats, see the date and time topic and the numbers and units topic.
Write for a global audience
Section titled “Write for a global audience”Examples
- ✓ Support hours are reduced from September through November.
- ✗ Support hours are reduced during the fall.
Rationale
A reference that depends on one language or culture can lose its meaning in another. State the intended meaning directly.
Avoid idioms and slang
Section titled “Avoid idioms and slang”global-003 should GuidesAPI docsMarketing Don’t use idioms, colloquialisms, slang, or culturally specific expressions.
Examples
- ✓ If the deployment fails, restart the setup from the beginning.
- ✗ If the deployment fails, you’re back to square one.
Rationale
The meaning of an idiom or slang term cannot always be derived from its individual words, and a literal translation may lose it. Plain wording states the meaning directly.
Avoid culture-specific references
Section titled “Avoid culture-specific references”global-005 should GuidesAPI docsMarketing Avoid references that depend on knowledge of a particular culture, including holidays, sports, traditions, and regional practices.
Examples
- ✓ Traffic doubles during the November promotion.
- ✗ Traffic doubles during the Thanksgiving promotion.
Rationale
Readers might not recognize particular holidays, sports, traditions, or regional practices, and translators might not have an equivalent reference. Name the date, event, or behavior that matters.
Avoid humor
Section titled “Avoid humor”global-006 should GuidesAPI docsMarketing Don’t use humor in content intended for a global audience.
Examples
- ✓ Delete the pod.
- ✗ Delete the pod. Don’t worry, it had a good life.
Rationale
Humor depends on language and shared cultural context. A joke can become confusing or inappropriate when translated or read in another culture.
Put information in text, not images
Section titled “Put information in text, not images”global-007 should GuidesAPI docsMarketing Use images sparingly in documentation. Put new information in body text rather than only in a figure because localization systems don’t translate text embedded in images.
Examples
- ✓ Set Connection timeout to 30 seconds.
- ✗ See the following screenshot for the required timeout settings.
Rationale
Localization and accessibility tools can process body text, but not text that is flattened into an image.
Define localization terms distinctly
Section titled “Define localization terms distinctly”global-009 should GuidesAPI docsMarketing Define localization, translation, and internationalization as distinct terms when introducing them in documentation.
Examples
- ✓ Internationalization prepares a codebase for multiple locales. Localization adapts a product for one locale. Translation converts text from one language to another.
- ✗ Localization, translation, and internationalization are different names for preparing an app for other languages.
Rationale
Each term names different work. Using the terms interchangeably hides which work a team must perform.
Applicable rules from other topics
Section titled “Applicable rules from other topics”- Default to active voice
passive-001should - Imperative mood for instructions
tense-005should - Prefer plain words
clarity-002should - Write concisely
clarity-003should - Keep sentences short
clarity-005should - Limit stacked noun modifiers
clarity-007should - Replace unclear phrasal verbs
clarity-009should - Avoid non-English words and abbreviations
clarity-004should - Don't drop articles
sentence-004should - Abbreviations and translation
abbr-011should - Avoid uncommon contractions
voice-004must - Prefer roles to names in examples
incl-008should - Avoid US-centric examples
incl-010should - Unambiguous date formats
datetime-001should - ISO currency codes
num-021should
Deprecated rules
Section titled “Deprecated rules”global-002(retired 2026-09-13): “Keep content clear and concise. Use simple sentence structures to support readers, translators, and people who use assistive technologies.” It restated clarity-002, clarity-003, and clarity-005, which this page now lists under “Applicable rules from other topics”; the assistive-technology clause belongs to the accessibility topic. The ID stays reserved and is never reused.global-004(retired 2026-09-13): “Use active voice in most content. Write procedure steps in imperative mood.” It restated passive-001, which holds the active-voice default and the cases where passive voice is the better choice, and tense-005, which holds the imperative mood for procedures. The translation reasons for both moved into those rules’ rationales, and this page lists both under “Applicable rules from other topics”. The ID stays reserved and is never reused.global-008(retired 2026-09-13): “When examples use names of people, places, or organizations, consider whether they reflect the diversity of your audience.” Merged into incl-008, which now prefers a role over a name and, when names are needed, varies them by region, culture, and gender. This page lists incl-008 under “Applicable rules from other topics”. The ID stays reserved and is never reused.