writing clear documentation for a global market
Many people who do not speak English as a first language struggle to understand English texts. Human translation is expensive. Machine translation (MT) frequently does not work. Global English offers a solution to these three related problems. Many good style guides exist. Why do technical writers need another guide to writing style? But unlike many other guides, The Global English Style Guide covers grammatical structures, not only particular terms.
The book has more than 200 pages of text (plus 4 appendices) that give detailed explanations of both good practice and bad practice. John Kohl writes clearly, and he explains the reasons for the guidelines. His guidelines are based on practical work at SAS Institute, where he works as a technical author. Most technical writers know some of the guidelines already. For example, restrict the use of the passive voice; use language literally; and simplify the writing style. However, many guidelines may be new. For instance, until I read the book, I used all these sentence structures:
- However, you can put an adverb in many locations.
- You can, however, put an adverb in many locations.
- You can put an adverb in many locations, however.
Now, I put an adverb at the start of a sentence, because in that location, the adverb helps to show the reader the logical connection with the previous sentence.
Both of the following sentences are grammatically correct:
- Set up the system.
- Set the system up.
Now, as far as possible, I always use the first structure, and keep the parts of a phrasal verb together. Keeping the parts of the verb together increases consistency, improves machine translation, and helps non-native speakers who do not know the particular verb.
A full chapter and an appendix show how to improve readability and translatability by using syntactic cues. A syntactic cue is a part of language that helps a reader to identify parts of speech and to analyse the structure of a sentence. Sometimes, syntactic cues are optional, but excluding them can cause ambiguity. Kohl gave a humorous example. The grammatically correct sentence, “Do not dip your bread or roll in your soup” has two possible meanings:
- Do not dip your bread or your roll in your soup.
- Do not dip your bread in your soup, and do not roll in your soup.
If readers are aware of the second interpretation, they know that it is incorrect. However, with technical texts, if a writer does not include optional syntactic cues, a reader’s interpretation may be incorrect.
With Global English, a writer can use all grammatical structures and all terms, unless the guidelines prohibit the grammar or the term. Additionally, the primary rule of Global English is, ‘do not make any change that will sound unnatural to native speakers of English’.
An alternative method for writing clear text is to use a controlled language. With a controlled language, a writer can use only grammar and terms that are permitted. Despite the different methods, many of the Global English guidelines agree with controlled language guidelines.
The subtitle of the book refers to writing documentation. However, most of the guidelines apply to copywriting as much as to technical writing. All writers who want to reach a global audience, to decrease translation costs, or to make their texts as clear as possible will benefit highly from this book.
Review by Mike Unwalla © 2008
John R, Kohl, The Global English style guide: writing clear, translatable documentation for a global market. Cary, NC: SAS Institute Inc. 2008, ISBN 9781599946573.
More on writing skills
More on language
More on grammar