Re: Docs for Users who have English as a Second Language

Subject: Re: Docs for Users who have English as a Second Language
From: Charlotte Claussen <charlotteclaussen -at- gmail -dot- com>
To: Peter Neilson <neilson -at- windstream -dot- net>
Date: Sun, 26 Apr 2020 23:13:47 +0100

"Be ready to resolve those reviewers' suggestions that you should use
the passive voice. Americans tend to avoid the passive in technical
writing, which can lead to a feeling that Americans are too brash."

Yes, I get that a lot! I live in the UK, and Brits are specialists in
convoluted, indirect, inactive language.

That said, the UK government are known for clear language, and Plain
English is mandatory on gov.uk:
https://www.gov.uk/guidance/content-design/writing-for-gov-uk#plain-english

The US government also have guidelines on Plain English:
https://plainlanguage.gov/about/definitions/

This site can also be helpful:
https://readabilityguidelines.co.uk/

This will help both native speakers and ESL readers.

Specifically for ESL readers, you can start with looking at this:
https://hodigital.blog.gov.uk/2015/12/29/tips-for-writing-for-non-native-english-speakers/

Also, be aware that jargon might be the right thing if you're speaking to
specialists. If they're all educated in the same field, then professional
terminology can be easier for them to understand than your "translation" to
layman's terms. As Peter said, try to get reviewers from your target
audience.

/Charlotte


On Sat, 25 Apr 2020 at 23:47, Peter Neilson <neilson -at- windstream -dot- net> wrote:

> (1) Avoid slang. Keep sentence structure simple. For example, it's
> probably all right to say, "If you want result X, do procedure Y. Some
> precautions are (blah, blah, blah, blah)." The reversed construction, "Do
> procedure Y, involving (blah, blah, blah, blah) if you want result X," is
> probably too convoluted.
>
> (2) If you like to use analogies from US sports, baseball is okay for
> Japan, but American football probably is not.
>
> (3) Try as hard as you can to get a reviewer or three from your target
> audience.
>
> (4) Be ready to resolve those reviewers' suggestions that you should use
> the passive voice. Americans tend to avoid the passive in technical
> writing, which can lead to a feeling that Americans are too brash. Some
> ESL learners are taught that the passive is the preferred construction,
> even though it sometimes creates ambiguity.
>
> These suggestions may by now be old fashioned. I recently came across a
> well-done mathematical explanation written by a high-school student in
> China. It was completely clear and straightforward, and in American
> English.
>
> Enjoy "Chinglish" while you still can; it is fast fading. No longer do we
> find the amusing message once written on the box with an alarm clock,
> "Thank you to perfection of alarming mechanism you never awake when you
> sleeping."
>
> On Sat, 25 Apr 2020 17:30:33 -0400, vinnie tieto <vtieto -at- sbcglobal -dot- net>
> wrote:
>
> > Do you have any tips for maximizing the effectiveness of docs that are
> > in English but must be easily digested by users in other countries like
> > Japan or China whose English may be lacking somewhat? I believe the
> > audience would be primarily engineers, but it may also consist of some
> > less technical users. The content will probably be highly technical
> with
> > lots of acronyms and jargon.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | https://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as charlotteclaussen -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Docs for Users who have English as a Second Language: From: vinnie tieto
Re: Docs for Users who have English as a Second Language: From: Peter Neilson

Previous by Author: Re: Docs for Users who have English as a Second Language
Next by Author: In-Browser Transforms was RE: Programming language
Previous by Thread: Re: Docs for Users who have English as a Second Language
Next by Thread: Re: Docs for Users who have English as a Second Language


What this post helpful? Share it with friends and colleagues:


Sponsored Ads