English serves as lingua franca within the open supply group. To scale back translation prices, many groups have switched to English because the supply language for his or her documentation. But surprisingly, writing in English for a world viewers doesn’t essentially put native English audio system in a greater place. On the opposite, they have an inclination to overlook that the doc’s language may not be the viewers’s first language.
Let’s take a look on the following easy sentence for example: “Encrypt the password utilizing the foo bar command.” Grammatically, the sentence is right. Given that ‘-ing’ kinds (gerunds) are regularly used within the English language and most native audio system contemplate them a chic means of expressing issues, native audio system normally don’t hesitate to phrase a sentence like this. On nearer inspection, the sentence is ambiguous as a result of “using” might refer both to the thing (“the password”) or to the verb (“encrypt”). Thus, the sentence might be interpreted in two other ways:
- “Encrypt the password that makes use of the
foo barcommand.” - “Encrypt the password through the use of the
foo barcommand.”
As lengthy as you’ve got earlier information concerning the subject (password encryption or the foo bar command), you possibly can resolve this ambiguity and appropriately determine that the second model is the supposed that means of this sentence. But what when you lack in-depth information of the subject? What if you’re not an professional, however a translator with solely basic information of the topic? Or if you’re a non-native speaker of English, unfamiliar with superior grammatical kinds like gerunds?
Even native English audio system want coaching to put in writing clear and simple technical documentation. The first step is to lift consciousness concerning the usability of texts and potential issues, so let’s take a look at seven guidelines that may assist keep away from frequent pitfalls.
1. Know your audience and step into their footwear.
If you’re a developer writing for finish customers, view the product from their perspective. Does the construction replicate the customers’ targets? The persona technique may help you to deal with the audience and supply the appropriate degree of element to your readers.
2. Follow the KISS precept—maintain it quick and easy.
The precept might be utilized on a number of ranges, comparable to grammar, sentences, or phrases. Here are examples:
- Use the only tense that’s applicable. For instance, use current tense when mentioning the results of an motion:
- “
Click ‘OK.’ The ‘Printer Options’ dialog will seem.” → “Click ‘OK.’ The ‘Printer Options’ dialog appears.”
- “
- As a rule of thumb, current one thought in a single sentence; nevertheless, quick sentences aren’t mechanically simple to grasp (particularly if they’re an accumulation of nouns). Sometimes, trimming down sentences to a sure phrase rely can introduce ambiguities. In flip, this makes the sentences extra obscure.
- Uncommon and lengthy phrases sluggish studying and may be obstacles for non-native audio system. Use easier options:
- “
make the most of” → “use” - “
point out” → “show,” “tell,” or “say” - “
prerequisite” → “requirement”
- “
three. Avoid disturbing the studying circulate.
Move particles or longer parentheses to the start or finish of a sentence:
- “
They aren’t, nevertheless, marked as put in.” → “However, they are not marked as installed.”
Place lengthy instructions on the finish of a sentence. This additionally ends in higher segmentation of sentences for automated or semi-automatic translations.
four. Discriminate between two fundamental data sorts.
Discriminating between descriptive data and task-based data is beneficial. Typical examples for descriptive data are command-line references, whereas how-to’s are task-based data; nevertheless, each data sorts are wanted in technical writing. On nearer inspection, many texts comprise a mix of each data sorts. Clearly separating the knowledge sorts is useful. For higher orientation, label them accordingly. Titles ought to replicate a bit’s content material and knowledge sort. Use noun-based titles for descriptive sections (“Types of Frobnicators”) and verbally phrased titles for task-based sections (“Installing Frobnicators”). This helps readers rapidly determine the sections they’re serious about and permits them to skip those they do not want for the time being.
5. Consider completely different studying conditions and modes of textual content consumption.
Some of your readers are already annoyed after they flip to the product documentation as a result of they may not obtain a sure aim on their very own. They may additionally work in a loud setting that makes it onerous to deal with studying. Also, don’t count on your viewers to learn cowl to cowl, as many individuals skim or browse texts for key phrases or search for subjects through the use of tables, indexes, or full-text search. With that in thoughts, have a look at your textual content from completely different views. Often, compromises are wanted to discover a textual content construction that works nicely for a number of conditions.
6. Break down complicated data into smaller chunks.
This makes it simpler for the viewers to recollect and course of the knowledge. For instance, procedures shouldn’t exceed seven to 10 steps (in response to Miller’s Law in cognitive psychology). If extra steps are required, cut up the duty into separate procedures.
7. Form follows operate.
Examine your textual content in response to the query: What is the function (operate) of a sure sentence, a paragraph, or a bit? For instance, is it an instruction? A outcome? A warning? For directions, use energetic voice: “Configure the system.” Passive voice could also be applicable for descriptions: “The system is configured automatically.” Add warnings earlier than the step or motion the place hazard arises. Focusing on the aim additionally helps detect redundant content material to assist remove fillers like “basically” or “easily,” pointless modifications like “already current” or “fully new,” or any content material that isn’t related to your audience.
As you might need guessed by now, writing is re-writing. Good writing requires effort and observe. Even when you write solely often, you possibly can considerably enhance your texts by specializing in the audience and following the foundations above. The higher the readability of a textual content, the simpler it’s to course of, even for audiences with various language expertise. Especially with regards to localization, good high quality of the supply textual content is vital: “Garbage in, garbage out.” If the unique textual content has deficiencies, translating the textual content takes longer, leading to increased prices. In the worst case, flaws are multiplied throughout translation and should be corrected in numerous languages.
This article is predicated on Tanja’s presentation, “Technical writing for an international audience,” at Open Source Summit Europe on October 24, 2017.