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.
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.
Write short sentences when possible. Long sentences can include problems…
complex use of tenses
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.
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 once the definite article is inserted. Compare “Block the open port on the catheter fitting.” to “Block open the port on the catheter fitting.
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
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: 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.
What must be 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 maintain our glossary and internal 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, particularly ‘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.
Do not use smart quotes or smart apostrophes. Prefer the straight versions.
Avoid clipped terms.
stat, spec, app, quotes, rep
“The mobile app” is the correct term.
Do not use Latin abbreviations.
Do not use non-technical abbreviations.