global-001 should GuidesAPI docsMarketing Write with a global audience in mind; avoid culturally specific references, idioms, and language that may be difficult for non-native English speakers or translators.
Globalization
Documentation is read — and often machine-translated — worldwide. These rules remove language and references that assume a particular country, culture, or native command of English. Formatting concerns such as dates and units are covered on their own pages.
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
Culture-specific references and idioms do not carry across languages, so avoiding them keeps the content readable worldwide.
Keep structure clear and simple
Section titled “Keep structure clear and simple”global-002 should GuidesAPI docs Keep content clear, concise, and simply structured to support all readers, including those using screen readers.
Avoid idioms and slang
Section titled “Avoid idioms and slang”global-003 should GuidesAPI docs Avoid idioms, colloquialisms, slang, and culturally specific expressions.
Examples
- ✓ If the deploy fails, restart the setup from the beginning.
- ✗ If the deploy fails, you’re back to square one.
Rationale
Idioms rarely translate and confuse non-native readers, so plain phrasing carries the meaning intact.
Use active voice and imperative steps
Section titled “Use active voice and imperative steps”global-004 should GuidesAPI docs Use active voice in most content; use imperative mood in procedures.
Examples
- ✓ Save the configuration file before you restart the server.
- ✗ The configuration file should be saved before the server is restarted.
Rationale
Active voice and imperative steps are the most direct forms and the easiest to translate.
Avoid culture-specific references
Section titled “Avoid culture-specific references”global-005 should GuidesAPI docs Avoid culturally specific references including holidays, sports, traditions, and regional practices.
Examples
- ✓ Traffic doubles during seasonal sales.
- ✗ Traffic doubles during the Thanksgiving sale.
Rationale
Holidays, sports, and regional practices are not shared worldwide, so an example built on them fails part of the audience.
Avoid humor
Section titled “Avoid humor”global-006 should GuidesAPI docs Avoid humor in global content.
Examples
- ✓ Delete the pod.
- ✗ Delete the pod. Don’t worry — it had a good life.
Rationale
Humor depends on shared context and rarely survives translation, so it distracts more than it helps in global content.
Put information in text, not images
Section titled “Put information in text, not images”global-007 should GuidesAPI docs Use images sparingly in documentation; convey new information through text rather than figures, since images are not translated.
Examples
- ✓ Set Connection timeout to 30 seconds.
- ✗ See the following screenshot for the required timeout settings.
Rationale
Text in images is not translated or read by assistive tech, so carrying new information in body text keeps it accessible and localizable.
Consider diversity in example names
Section titled “Consider diversity in example names”global-008 may GuidesAPI docsMarketingBlog When examples use names of people, places, or organizations, consider whether they reflect the diversity of your audience.
Rationale
Example names can signal who the documentation imagines its readers to be, but attempting cultural diversity without real familiarity often reads worse than acknowledging the context. Because several approaches are reasonable, this is a loose recommendation rather than a firm rule.
Define localization terms distinctly
Section titled “Define localization terms distinctly”global-009 should GuidesAPI docs Define localization, translation, and internationalization as distinct terms when introducing them in documentation.
Examples
- ✓ Internationalization prepares the codebase to support multiple locales; localization adapts the content for one locale.
- ✗ Localization (also known as internationalization) prepares your app for other languages.
Rationale
These terms are often used loosely and interchangeably, so defining them prevents confusion in content that discusses them.