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

["Peter Neilson" <neilson -at- windstream -dot- net>]

(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: