{"id":34866,"date":"2018-07-23T12:00:32","date_gmt":"2018-07-23T12:00:32","guid":{"rendered":"http:\/\/www.sickgaming.net\/blog\/2018\/07\/23\/5-tips-to-improve-technical-writing-for-an-international-audience\/"},"modified":"2018-07-23T12:00:32","modified_gmt":"2018-07-23T12:00:32","slug":"5-tips-to-improve-technical-writing-for-an-international-audience","status":"publish","type":"post","link":"https:\/\/sickgaming.net\/blog\/2018\/07\/23\/5-tips-to-improve-technical-writing-for-an-international-audience\/","title":{"rendered":"5 Tips to Improve Technical Writing for an International Audience"},"content":{"rendered":"
<\/div>\n

Learn how to\u00a0write\u00a0for an international audience in this article from our archives.<\/strong><\/p>\n

Writing in English for an international audience does not necessarily put native English speakers in a better position. On the contrary, they tend to forget that the document’s language might not be the first language of the audience. Let’s have a look at the following simple sentence as an example: \u201cEncrypt the password using the ‘foo bar’ command.\u201d<\/p>\n

Grammatically, the sentence is correct. Given that “-ing”\u00a0forms (gerunds) are frequently used in the English language, most\u00a0native speakers would probably not hesitate to phrase a sentence like this. However, on closer inspection, the sentence is ambiguous:\u00a0The word \u201cusing\u201d may refer either to the object (\u201cthe password\u201d) or to the verb (\u201cencrypt\u201d). Thus, the sentence can be interpreted in two different ways: <\/span><\/p>\n

As long as you have previous knowledge about the topic (password encryption or the ‘foo bar’ command), you can resolve this ambiguity and correctly decide that the second reading is the intended meaning of this sentence. But what if you lack in-depth knowledge of the topic? What if you are not an expert but a translator with only general knowledge of the subject? Or, what\u00a0if you are a non-native speaker of English who is unfamiliar with advanced grammatical forms? <\/span><\/p>\n

Know Your Audience<\/h3>\n

Even native English speakers may need some training to write clear and straightforward technical documentation. Raising awareness of\u00a0usability\u00a0and\u00a0potential problems is the first step. This article, based on my talk at Open Source\u00a0Summit EU<\/a>,\u00a0offers several useful\u00a0techniques. Most of them are\u00a0useful not only for technical documentation\u00a0but\u00a0also for\u00a0everyday written communication, such as writing email\u00a0or reports. <\/span><\/p>\n

1.\u00a0Change perspective.\u00a0<\/strong>Step into your audience’s shoes. Step one is to know your intended audience. If you are a developer writing for end users, view the product from their perspective. The persona technique<\/a>\u00a0can help to focus on the target audience and to provide the right level of detail for your readers. <\/span><\/p>\n

2. Follow the KISS principle.\u00a0<\/strong>Keep it short and simple. The principle can be applied to several levels, like grammar, sentences, or words. Here are some examples: <\/span><\/p>\n

Words: <\/em>Uncommon and long words slow down reading and might be obstacles for non-native speakers. Use simpler alternatives:<\/span><\/p>\n

\u201cutilize\u201d \u2192 \u201cuse\u201d<\/p>\n

\u201cindicate\u201d \u2192 \u201cshow\u201d, \u201ctell\u201d, \u201csay\u201d<\/p>\n

\u201cprerequisite\u201d \u2192 \u201crequirement\u201d<\/p>\n

Grammar: <\/em>Use the simplest tense that is appropriate. For example, use present tense when mentioning the result of an action: “Click OK<\/em>.\u00a0The Printer Options<\/em>\u00a0dialog appears.\u201d <\/span><\/p>\n

Sentences: <\/em>As a rule of thumb, present one idea in one sentence. However, restricting sentence length to a certain amount of words is not useful in my opinion. Short sentences are not automatically easy to understand (especially if they are a cluster of nouns). Sometimes, trimming down sentences to a certain word count can introduce ambiquities, which can, in turn, make sentences\u00a0even more difficult to understand. <\/span><\/p>\n

3. Beware of ambiguities. <\/strong>As authors, we often do not notice ambiguity in a sentence. Having your texts reviewed by others\u00a0can help\u00a0identify such problems. If that’s not an option, try to look at each sentence from different perspectives: Does the sentence also work for readers without in-depth knowledge of the topic? Does it work for readers with limited language skills? Is the grammatical relationship between all sentence parts clear? If\u00a0the sentence does not meet these requirements, rephrase it\u00a0to resolve the ambiguity. <\/span><\/p>\n

4. Be consistent. <\/strong>This applies to choice of words, spelling, and punctuation as well as phrases and structure. For lists, use parallel grammatical construction. For example:<\/span><\/p>\n

Why white space is important: <\/span><\/p>\n

5. Remove redundant content.<\/strong> Keep only information that is relevant for your target audience. On a sentence level, avoid fillers (basically, easily) and unnecessary modifications:<\/span><\/p>\n

“already existing” \u2192\u00a0“existing”<\/p>\n

“completely new” \u2192\u00a0“new”<\/p>\n

As you might have guessed by now, writing is rewriting. Good writing requires effort and practice. But even if you write only occasionally, you can significantly improve your texts by focusing on the target audience and by using basic writing techniques. The better the readability of a text, the easier it is to process, even for an audience with varying language skills. When it comes to localization especially, good quality of the source text is important: Garbage in, garbage out. If the original text has deficiencies, it will\u00a0take\u00a0longer to translate the text, resulting in higher costs. In the worst case, the flaws will be\u00a0multiplied during translation and need\u00a0to be corrected in various languages.\u00a0<\/span><\/p>\n

Driven by an interest in both language and technology, Tanja has been working as a technical writer in mechanical engineering, medical technology, and IT for many years. She joined SUSE in 2005 and contributes to a wide range of product and project documentation, including High Availability and Cloud topics.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"

Learn how to\u00a0write\u00a0for an international audience in this article from our archives. Writing in English for an international audience does not necessarily put native English speakers in a better position. On the contrary, they tend to forget that the document’s language might not be the first language of the audience. Let’s have a look at […]<\/p>\n","protected":false},"author":2,"featured_media":34867,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[40],"tags":[],"class_list":["post-34866","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-linux-freebsd-unix"],"_links":{"self":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/34866","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/comments?post=34866"}],"version-history":[{"count":0,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/34866\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media\/34867"}],"wp:attachment":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media?parent=34866"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/categories?post=34866"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/tags?post=34866"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}