How can I ensure that my documentation is understandable both for native and non-native speakers?

Question

In short: When writing documentation that will be read both by Anglophones and non-native speakers of English who have various levels of language proficiency, how do I make sure that both these recipient groups find the text comprehensible and easy to read?

While numerous style guides (example: the widely praised MailChimp style guide) advocate some variety of 'friendly, informal, straightforward', adopting a style like this can be at odds with making the text easily understandable for non-native audiences.

There are some strategies which would satisfy both groups of recipients: using simple sentence structures, applying consistent terminology, avoiding cultural references, etc. But in some aspects of style and tone, the two groups might need different treatments.

Example: The use of contraction such as "it's" or "you'll" is permitted by sources such as Microsoft Manual of Style, or even the more conservative Chicago Manual of Style, and using only long form may be considered overfly stuffy and formal. On the other hand, I've been told by non-natives that contractions of that sort should be replaced with more explicit full phrasing.

How can I reconcile the needs of these two audiences?

Answer 1

In terms of just writing for non-native speakers, the Simple English Wikipedia has some good guidelines for writing articles that seem applicable here.

There's a fair amount of detail and some examples in the article itself, but a brief summary would be:

• Prefer common words to more unusual ones
• Use simple grammatical structure: avoid long compound sentences with multiple clauses if possible
• Do not use idioms
• Do not use contractions "as this allows learners to recognize familiar grammatical patterns"
• Use correct grammar and spelling

Documentation that sounds a bit too formal isn't necessarily a bad thing, but I agree that it can be at odds with wanting to make it flow well.

There's probably a balance to strike, and how far you lean one way or the other probably depends on what kind of documentation it is. How-tos are often more informal, sometimes with humour mixed in, while it's more important for technical reference documentation that information is absolutely expressed accurately and precisely.

Overall, you'll probably need to consider your audience when making this choice: if you're happy making your text a little less easy to read for non-native readers, you may be able to make it more comfortable reading for native speakers. There's no perfect method to satisfy both, I think.

Answer 2

Documentation can be equally understandable for both native and non-native speakers. But in that case, it might not be equally appealing to native and non-native speakers.

Documentation that is written in a simple, easily understandable language will probably get the message across for both groups. But it might read unfamiliar or awkward to native speakers and might be problematic from a marketing perspective. As an example, Simplified Technical English comes to mind (https://en.wikipedia.org/wiki/Simplified_Technical_English).

Answer 3

I'd say a major factor is to avoid idioms or local terms/phrases. Generally that will make it more difficult for an international audience

For example, don't use terms like "don’t get bent out of shape," "it’s not rocket science", or "it doesn’t cost an arm and a leg."

Answer 4

I'd say you're on the right track with the common strategies you list (simple sentence structure, etc). When there's a conflict in strategies, you may have to do a little deeper audience analysis. Or you can prioritize -- for example, the native audience may not "need" a casual tone as much as the non-native audience "needs" clarity. Maybe you decide to minimize contractions (for example, "it's" and "don't" may be straightforward enough for your non-native audience) and generally keep the word choice and sentence structure simple and consistent. It's probably good for both audiences to avoid idioms.