Everyone has come across examples of confusing instructions and unhelpful help files. Often, however, it’s actually not the original instructions that are poor, but the translation into the user’s language. Even if the grammar and the spelling are absolutely correct, an improper form of translation can make the instructions ambiguous, hard to read, or even wrong and useless.
If you are a translator or somebody who charges a translator with a translation job, learning how technical writers have designed their documents for clearness and simplicity will help you preserve the original document’s quality. The main difference compared to translating other sorts of texts is that in technical documentation, clearness and simplicity take precedence. Things that are sometimes considered to be poor style when translating a novel or marketing materials, are often intended in technical documentation. For example, in technical documentation using the same words all over again is not a sin, but a virtue. Diversified, complex language that makes a novel or sales brochure entertaining and interesting can be exactly what makes a user manual incomprehensible.
Translators often are the first readers of new manuals. If translators find an error, they should take the time to inform the document’s author. Likewise, translators should not hesitate to ask the author for clarification when they don’t understand the text that they are translating. First, it also provides some valuable feedback to the author to see where readers begin to struggle; second, it is essential for a precise translation. Asking is not a sign of weakness but shows that a translator cares about quality. Never, ever should a translator attempt to conceal a lack of understanding by writing something that’s so vague that, strictly speaking, it’s not wrong. If it isn’t clear, it is wrong.
However, everyone involved should also be aware of the fact that asking questions and eliminating doubts takes a translator some additional time and thus costs some additional money. The contract and the compensation agreed on with the translator should reflect this.
Good user assistance is:
correct and unambiguous
written in a way that makes it easy to mentally process the given information
written in a way that makes it easy to act upon the given instructions
written in a way that makes it easy to remember the given information
Rule 1: Keep it simple and stupid
You are not translating an essay. You don’t have to impress your readers. Provide information that everybody can understand, even readers who:
don’t speak the document’s language as their first language
aren’t sitting in a silent office but who, for example, are standing in a noisy production hall
don’t have much time
are frustrated because they didn’t succeed without reading the manual
So keep your translation simple and stupid (KISS principle):
Write short sentences
Avoid subordinate and nested sentences
Use simple grammar
Use simple words
Plain language is not evidence of poor education. Plain language is the foundation of clear user assistance. Don’t try to impress your readers or your employer or client with your sophisticated language skills.
No: The PIN, which must not be noted on the credit card, consists of four digits.
Yes: The PIN consists of four digits. Don’t note the PIN on the credit card.
No: Many popular programs — for example, office suites, image editors, web browsers and email clients — still come with poor documentation.
Yes: Many popular programs still come with poor documentation. These include office suites, image editors, web browsers and email clients.
Rule 2: Keep the order
Technical writers put the most important information into the most prominent position in front of a sentence or heading. When readers skim a text, what comes at the beginning is easier for them to find than what comes somewhere else. Readers assume that what comes right at the beginning is more important than what comes somewhere else. Readers remember better what comes at the beginning than what comes somewhere else. So don’t change the given order within a sentence or heading.
Rule 3: Be specific
When reading instructions, users are looking for clear answers. Don’t be vague. Don’t be ambiguous. If readers notice that a phrase is unclear or ambiguous, this results in uncertainty. If readers do not notice that a phrase is unclear or ambiguous (which often happens), this may result in misunderstanding and failure.
The key rule on how to be specific is to avoid all sorts of vague terms. If you are unsure yourself about what the author meant, don’t hesitate to ask.
No: If you’ve filled in all fields correctly, the results window should appear.
Yes: If you’ve filled in all fields correctly, the results window appears.
No: The action should be finished quickly.
Yes: You need to finish the action within one minute.
No: between 7 and 11 (Unclear: are 7 and 11 included?)
Yes: from 7 through 11
Some typical examples of vague terms are words and phrases such as and so on, and/or, can, corresponding, etc., may, maybe, object, ought to, quite, rather, respectively, should and some.
Rule 4: Be concise
Omit all words and syllables that are nothing but empty calories. Every word and character saved is a step toward more clarity. The only exception to this rule is: don’t be concise at the expense of clarity. If you need more words to be more specific or to avoid ambiguity, go ahead and include them.
No: The cable is about ten meters in length.
Yes: The cable is ten meters long.
No: It has a round shape.
Yes: It’s round.
No: If you’re a user who has experience in this field, use expert mode.
Yes: If you’re an experienced user, use expert mode.
No: It’s necessary to enter a value.
No: You’re required to enter a value.
Yes: You must enter a value.
Rule 5: Be consistent
A consistent document is easy to read because in a consistent document readers can fully focus on the content. In addition, a consistent document makes a professional impression, which increases credibility and builds up confidence.
Consistency involves consistent spelling, punctuation and choice of words. Aim for consistency not only within each document but also among all documents.
No: If you’ve purchased a new application, you must first install the software before you can use the program.
Yes: If you’ve purchased a new program, you must first install this program before you can use it.
Rule 6: Be parallel
In technical writing, repetitive structures aren’t a sign of weak style but enhance readability. Parallel structures make the content more predictable. If structures are parallel, readers don’t have to mentally process a new structure but can, instead, attend to the words alone.
Try to keep all headings within a chapter, section or other unit grammatically parallel, especially those on the same level. If it doesn’t make sense to keep all headings parallel, try to keep at least as many subsequent headings as parallel as possible.
No:
Washing of trucks
Washing cars
How can you wash a motorcycle?
How to wash a bicycle
No:
Washing trucks
Washing cars
Washing a motorcycle
Washing a bicycle
Yes:
Washing trucks
Washing cars
Washing motorcycles
Washing bicycles
In lists and tables, don’t mix full sentences with sentence fragments.
No: In a document, white space is important for the following reasons:
ü visual separation of sections
ü attention focus
ü white space breaks content into smaller chunks
Yes: In a document, white space is important because it:
ü visually separates sections
ü focuses attention
ü breaks content into smaller chunks
In procedures, typically begin all steps with a verb.
No: To print a picture:
1. Open the image file.
2. Choose File > Print > Options.
3. Next, select the option Photo Quality.
4. Finally, the Print button must be clicked.
Yes: To print a picture:
1. Open the image file.
2. Choose the menu command File > Print > Options.
3. Select the option Photo Quality
4. Click the Print button.
In general, balance parts of a sentence with their correlating parts (nouns with nouns, prepositional phrases with prepositional phrases and so on). If you need to repeat a word, this is perfectly OK.
No: The program can be used to manage annual reports, budgets, and financial planning.
Yes: You can use the program for managing annual reports, for budgeting, and for financial planning.
Yes: You can use the program to manage annual reports, budgets, and financial plans.
No: Whether at home or when working, DemoProduct helps you.
Yes: At home or at work, DemoProduct helps you.
No: Your alternatives are to use feature A or using feature B.
Yes: Your alternatives are to use feature A or to use feature B.
Rule 7: Use the present tense
Write as if you were talking over the reader’s shoulder. Write as if the reader was using the application right now. Use the present tense. Using the present tense implies that things always happen as described, which inspires confidence. Save the future tense for things that will happen in the future.
No: Click the “Send” button. Your email will be sent to the recipient.
Yes: Click the “Send” button. The program now sends your email to the recipient.
No: The “Printer Options” window will appear.
Yes: The “Printer Options” window appears.
Rule 8: Use the active voice
Use the active voice rather than the passive voice. The active voice always makes clear whether the reader must act or whether the system acts automatically. Also the active voice is shorter and easier to understand than the passive voice. It directly tells the users what to do. This is particularly important in warning messages.
No: The active voice is to be used.
Yes: Use the active voice.
No: To enter the room, the door must be unlocked.
No: The door must be unlocked to enter the room.
No: One must unlock the door before the room can be entered.
No: In order to enter the room, it’s necessary that the door gets unlocked.
Yes: To enter the room, unlock the door.
Rule 9: Feel free to start
sentences simply
There’s no rule that prohibits you from starting a sentence with simple words like but, so, also, because, therefore, thus and so on. In user assistance, using these words at the beginning of a sentence is not poor style. Using these words is much better than clumsy and overblown phrases such as as a consequence of, as a result of, or due to the fact that.
No: Due to the fact that you’re reading this text, your translations will improve.
Yes: Because you’re reading this text, your translations will improve.
Rule 10: Feel free to
repeat a word
When it adds clarity, don’t hesitate to use the same word over again. Don’t avoid using the same word twice in a sentence or in consecutive sentences because you think that this is poor style. In user assistance, the best style is clarity.
In sentences with and and or, make sure that it’s clear which terms an attribute relates to.
No: You need green paper and tape. (Unclear: must the tape also be green?)
Yes: You need green paper and some tape.
Words such as this, that, they, these, those, it, which and so on link ideas. Make sure that these words point unmistakably to one noun, one phrase or one clause so that your sentence isn’t ambiguous. If there’s any possibility of confusion, repeat the noun.
No: You can use the instrument to measure the PH value and the humidity of the soil. Note that this only works if the temperature is above 0 degrees Celsius. (Unclear: do both measurements need a minimum temperature? Also unclear: which temperature is important? The temperature of the soil? The air temperature? Maybe even both temperatures?)
Yes: You can use the instrument to measure the PH value and the humidity of the soil. Note that you can only measure the PH value if the soil temperature is above 0 degrees Celsius.
Don’t use awkward constructions like the former … the latter. These constructions aren’t ambiguous, but they’re extremely hard to read. Most readers do remember the statements, but they don’t remember which one came first. So they have to read the whole section again, which wastes their time, makes them feel stupid and doesn’t contribute to a positive user experience.
No: Type 657B devices are green. Type 657C devices are red. The former are made of plastic, whereas the latter are made of steel.
Yes: Type 657B devices are green and made of plastic. Type 657C devices are red and made of steel.
Rule 11: Add syntactic cues
Syntactic cues are words or punctuation marks that help readers to analyze the structure of a sentence more quickly and more reliably. This can enhance readability and often particularly helps readers who speak the document’s language as a second language. Also syntactic cues often eliminate ambiguities.
If you can add a syntactic cue, do so. The few extra characters or words are a good investment in clarity. However, inserting a syntactic cue isn’t always the best remedy for a poorly designed sentence. Sometimes it’s better to rephrase a sentence completely or to make two sentences out of one.
No: Programs currently running are indicated by icons in the Task bar.
Yes: Programs that are currently running are indicated by icons in the Task bar.
No: The advanced search feature is especially helpful for users familiar with regular expressions.
Yes: The advanced search feature is especially helpful for users who are familiar with regular expressions.
No: You can run macros using the Macro utility. (Ambiguous: does the Macro utility run the macros or do the macros use the Macro utility?)
Yes: You can run macros by using the Macro utility.
No: The program continues processing data after restoring the database.
Yes: The program continues to process data after it has restored the database.
No: Your data must not include leading blanks and semicolons. (Ambiguous: does the sentence mean writers should avoid using leading semicolons or all semicolons?)
Yes: Your data must not include semicolons and leading blanks. (The syntactic cue here is the reversed order of semicolons and blanks.)
Or: Your data must not include leading blanks and leading semicolons.
Rule 12: Be clear about what you’re referring to
When using words like this, these, that, those, it, they and them, make sure that it’s clear which subject you’re referring to. If it avoids ambiguity or improves readability, don’t hesitate to repeat the subject as often as necessary. Keep your text as stupid as possible. Clarity never is poor style. Usually, the topics that you’re talking about are challenging enough.
No: The bomb is connected to a red and to a blue wire. Cut it to defuse the bomb.
Yes: The bomb is connected to a red and to a blue wire. To defuse the bomb, cut the red wire.
Rule 13: Use strong verbs
Use strong verbs that keep your texts clear, simple and concise. Many people tend to use verbs converted into nouns because they feel that this makes their text sound more sophisticated. Avoid this to keep your text simple.
No: We held a meeting and reached a decision on the improvement of our translations.
Yes: We met and decided on how to improve our translations.
No: The first step is the deletion of all unnecessary words.
Yes: The first step is to delete all unnecessary words.
No: Our software can be of help to you.
Yes: Our software can help you.
No: There are four screens within the wizard.
Yes: The wizard consists of four screens.
Rule 14: Watch for -ed
Try to simplify or omit words that end with -ed.
No: Users who are located in France
Yes: Users in France
No: A study that was conducted by our company shows that
Yes: A study by our company shows that
No: centralized control
Yes: central control
No: improved results
Yes: better results
Rule 15: Watch for opening It and There
Review sentences that start with It is, There is or There are. Often, you can find a more concise solution.
No: It is often the case that sentences are much too long.
Yes: Often, sentences are too long.
No: There are some functions that help you save energy.
Yes: Some functions help you save energy.
No: There’s something wrong with this sentence.
Yes: Something is wrong with this sentence.
Rule 16: Avoid strings of nouns
Strings of nouns are hard to understand and sometimes even ambiguous. Avoid them if possible.
No: The device adapter card port signals (Ambiguous. We can’t tell whether this refers to the signals of the port, or to the port signals of the card)
Yes: The port signals of the device adapter card
No: Technical translation principles
Yes: Principles of translating technical documentation
Rule 17: Avoid unnecessary qualification
Don’t modify or qualify things that don’t need to be modified or qualified. Unnecessary qualification only adds useless words, but it doesn’t add any valuable information.
No: Both sentences tell you exactly the very same thing.
Yes: Both sentences tell you the same thing.
Conclusion
Translating technical documentation can be somewhat different from translating other sorts of texts. If you observe these principles during the translation process, you will be able to preserve the full quality of the original documents. It really doesn’t take much additional time, but the benefit can be tremendous. Your clients are going to appreciate it.
