12

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?

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:14

13

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.

  • 1
    I agree that there is a balance to strike. You probably must compromise one way or the other. I imagine, there might not be a good sweet spot to satisfy both groups of your given target audience. And if there is a sweet spot, it might vary between different target audiences. For example, if your target audience are non-native speaking, but educated high-profile professionals you can probably assume a certain level of English skills as opposed to average consumers. – Thorsten Konersmann Jan 24 '18 at 12:21
  • 1
    By the way, the level of English skills also varies significantly between countries in Europe, for exmaple. (Fun fact: This depends on whether movies and TV shows are ususally dubbed or only subtitled in that country.) – Thorsten Konersmann Jan 24 '18 at 12:21
  • As an added bonus - all of the tactics Aesin suggests will also make your text easier to localize. This may not be a concern now, but having something translation-ready can't hurt. Overall, seems like a winning strategy. – topicref Jan 24 '18 at 12:46
12

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

  • 2
    Indeed. A native speaker probably wouldn't misunderstand anything written in ASD-STE100, but it reads like it was written by a non-native speaker with limited writing skills, and some of its idioms would be marked wrong by an English teacher. – Robert Lauriston Jan 23 '18 at 18:59
  • 1
    To get a feeling how such very simple language reads, the book Thing Explainer: Complicated Stuff in Simple Words by Randall Munroe is another example (amazon.com link). The author uses only the 1,000 most common words to describe rather complex things like datacenters, tectonic plates, airliner cockpit controls, or biological cells. – Thorsten Konersmann Jan 24 '18 at 11:58
  • This doesn't really answer the question of how to make it understandable. I agree these are concerns but how does the OP make sure their document is understandable by both audiences? – Chad Jan 26 '18 at 15:27
  • That‘s true. See my comment on Aesin‘s answer. – Thorsten Konersmann Jan 26 '18 at 18:47
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."

2

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy