8. Guidelines for Writing Global English#

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.

8.1. Global Examples #

In addition to writing so that our text can be easily translated, remember that our audience is global, and make sure this is reflected in the examples that we use to illustrate concepts in our documentation. Use situations that people can relate to regardless of their culture, and use example names and email addresses that represent diverse ethnicities.

8.2. 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 is 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 once the definite article is inserted. Compare “Block the open port on the catheter fitting.” to “Block open the port on the catheter fitting.

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

Example nominalizations:

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

Here’s an example of a sentence drafted in the passive voice, and how it was rewritten in the active voice.

Passive: This method is typically applied to free text fields, including discussion posts and wiki articles.

Active: EdX typically applies this method to free text fields, including discussion posts and wiki articles.

TBD: gerunds

TBD: verb-centric writing

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

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

What must be 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.

8.6. Mood #

Avoid the subjunctive mood. Native English speakers have trouble with it. Prefer the indicative and imperative moods.

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

8.8. 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…”

8.9. Use (and Add to) the Glossary #

Use and maintain our glossary and internal 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.

Do not use smart quotes or smart apostrophes. Prefer the straight versions.

8.13. Abbreviations #

Avoid clipped terms.

Examples:

stat, spec, app, quotes, rep

Exception:

“The mobile app” is the correct term.

Avoid acronyms.

Do not use Latin abbreviations.

Do not use non-technical abbreviations.

8.14. References to Explore #

The Global English Style Guide JR Kohl

Microsoft Manual of Style 4th ed.

Guidelines for Writing Global English

Contents