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.
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.
- Do not damage clarity.
- Do not sacrifice the syntactic cues provided by definite and indefinite articles.
- Do not omit important information. Be explicit.
“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.
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.
utilization, operation, facilitation, activation, completion, reaction, improvement, movement, discovery, difficulty…
TBD: verb-centric writing
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.
Avoid ambiguous pronouns, particularly impersonal pronouns. All kinds of words can sneak into use as pronouns.
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.
In order to sterilize a reusable product using an autoclave, it must first be properly cleaned and disinfected.
Avoid broad-reference pronouns.
Our new monitor has virtually no background noise, which should substantially reduce the number of false positives.
Avoid the subjunctive mood. Native English speakers have trouble with it.
Prefer the indicative and imperative moods.
Be sensitive to words that are used as both nouns and verbs, and provide context for them.
Display it on the screen.
Change the scroll rate on the display.
Eliminate unusual non-technical words.
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.
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.
“top”, “cap”, and “cover” are translated and understood as three different things, not as the same thing.
Avoid contractions. They introduce ambiguity, particualrly 'd and 's. Use other means to convey a friendly, informal tone.
Plan for expanded text. Expansion of 25% is common, so incorporate white space in flowcharts, blocks of text, UI strings...
Avoid slashes. They introduce ambiguity.
Avoid em dashes. Putting non-restrictive relative clauses into separate sentences leads to simpler, clearer writing.
Avoid clipped terms.
stat, spec, app, quotes, rep
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.