Guidelines for Writing Global English

Owned by Alison Hodges
Apr 03, 2023
2 min read

We, the edX documentation team, have the privilege of writing for diverse audiences. Soon, our work will be translated into languages other than English, and reach an even broader set of readers. To prepare, we need to continue to apply core technical writing principles. We also need to expand our skill sets to follow guidelines that will make what we write even easier for a global audience to understand and translate.

Short Sentences

Write short sentences when possible. Long sentences can include problems...

  • complex grammar
  • complex use of tenses
  • ambiguous pronouns
  • long clauses
  • complex modifier strings

Try to limit sentences to 20-30 words. Rule of thumb: if you run out of breath when you read a sentence aloud, it’s too long. 

However!

  • Do not damage clarity.
  • Do not sacrifice the syntactic cues provided by definite and indefinite articles.
  • Do not omit important information. Be explicit.

Example: 

“Block open port on catheter fitting” could mean completely different things.

  • Block the open port on the catheter fitting.
  • Block open the port on the catheter fitting.

and more...

Active Voice and Active Verbs

Use the active voice.

Use active verbs.

Avoid nominalizations (nouns made from verbs or adjectives) as they disguise the actors.

Examples:

utilization, operation, facilitation,  activation, completion, reaction, improvement, movement, discovery, difficulty… 

TBD: gerunds

TBD: verb-centric writing

Bulleted Lists

Write bulleted lists so that they are translatable.

  • Introduce the list with a complete sentence.
  • Do not use the bulleted points to complete an introductory sentence fragment.
  • Make sure each bulleted point can stand alone. 

This approach might increase word count, but it decreases translation cost.

Pronouns

Avoid ambiguous pronouns, particularly impersonal pronouns.  All kinds of words can sneak into use as pronouns. 

Examples:

all, another, any, each, either, few, following, many, neither, none, one, other, rest, same, several, some, such, that, them, these, those

Ask “of what?”, “of which?” or “as what?” when you use these words.

Example:

In order to sterilize a reusable product using an autoclave, it must first be properly cleaned and disinfected.

Avoid broad-reference pronouns. 

Example:

Our new monitor has virtually no background noise, which should substantially reduce the number of false positives. 

Mood

Avoid the subjunctive mood. Native English speakers have trouble with it.

Prefer the indicative and imperative moods.

Provide Context

Be sensitive to words that are used as both nouns and verbs, and provide context for them.

Examples:

Display it on the screen.

Change the scroll rate on the display. 

Word Choice

Avoid jargon.

Avoid colloquialisms.

Avoid humor.

Eliminate unusual non-technical words.

Examples:

and so forth, albeit, heretofore, whilst, ...

Use nouns as nouns, and verbs as verbs. (More on that elsewhere!)

Beware of commonly used constructions that introduce ambiguity.

Examples:

Replace "For more information on..." with "For more information about..."

Replace "When the process completes, you can..." with "After the process completes..."

Use (and Add to) the Glossary

Use and maintain our list* of preferred terms and phrases. Be consistent in terms used.

Example:

“top”, “cap”, and “cover” are translated and understood as three different things, not as the same thing.

Contractions

Avoid contractions. They introduce ambiguity, particualrly 'd and 's. Use other means to convey a friendly, informal tone.

White Space

Plan for expanded text. Expansion of 25% is common, so incorporate white space in flowcharts, blocks of text, UI strings...

Punctuation

Avoid slashes. They introduce ambiguity.

Avoid em dashes. Putting non-restrictive relative clauses into separate sentences leads to simpler, clearer writing. 

Abbreviations

Avoid clipped terms.

Examples:

stat, spec, app, quotes, rep

Avoid acronyms.

Do not use Latin abbreviations.

Do not use non-technical abbreviations.

 

References to Explore

The Global English Style Guide JR Kohl

Microsoft Manual of Style 4th ed.