# Writing Documentation for an International Audience

The guidelines in this chapter can help you to create documentation that is suitable for an international audience.

## Goals of the Writer

When you create technical documentation for an international audience, you should aim to achieve the following objectives:

- Ensure technical accuracy and linguistic clarity, so that translated versions retain the technical accuracy of the original language version.

- Facilitate the work of the translators. Documentation that is wordy or ambiguous creates more work for the translators. You should aim to reduce to a minimum the time and effort that the translator needs to translate your documentation.

- Ensure that the documentation is suitable for internationalization, localization, and translation. Consider the following factors:

  - Internationalization involves the creation of documentation for use in many different cultures, or documentation that is easy to translate into many languages.

  - Localization involves the conversion of documentation into another language or culture.

  - Translation refers to the process of translating documents into another language. Translation is just one part of localization. The guidelines in this section can help you to create technical documentation that translators can easily translate into different languages.

## Cultural Differences

You need to think globally when you write for an international audience. Conventions that you take for granted in your own language and culture are often different in other parts of the world. Keep in mind the following guidelines when you write for an international audience:

- Do not use examples that are culturally bound, such as names of places that are unrecognizable to people in other countries.

- Do not use political or religious references. Make sure that when you give examples, the machine names, login names, and so on are not culturally offensive. Do not use examples from political or religious spheres.

- Be aware that calendar conventions vary from country to country.

- Do not use humor. A great joke in one culture can provoke complete bewilderment in another culture.

- Do not use colloquial language. Everyday sayings are very difficult to translate and are usually meaningless if the translator translates the saying word-for-word. If you use colloquial phrases then the translator has to interpret what you want to say, which can cause ambiguity or inaccuracy.

## How to Write for Translation

This section provides you with specific rules about how to write for translation, with practical examples. The topics in this section are the most common causes of translation errors. You can use the following basic grammar guidelines to avoid most situations that cause difficulty for translators and readers. The examples for each topic might relate to releases of the GNOME Desktop that predate the release you are working with, nevertheless the linguistic points remain valid.

Topic 1 | Gerund
Rule | Do not use a gerund where a translator can mistake the gerund form for an adjective. The most common place for this problem to occur is when a gerund immediately precedes a noun.
Example | Clicking Programs opens the Programs menu.
Rewrite | Click on Programs to open the Programs menu.
Exceptions | You can use the gerund in section headers, for example: Using the Menu Editor. You can use the gerund in the present continuous tense, for example: The application is running. You can use the gerund for the term Settings, for example, when you describe controls in a dialog. You can use the gerund for the adjective following, when you introduce a list or a procedure. You can use gerunds preceded by an article when the gerund is a noun, for example, the setting.

Topic 2 | Passive voice
Rule | Use the active voice wherever you can. If you do use the passive voice, analyze the text to see if you can say the same thing in the active voice.
Example | The Menu Editor is started from the Main Menu.
Rewrite | You start the Menu Editor from the Main Menu.
Exceptions | Sometimes you cannot avoid the passive voice. If the sentence does not make sense in the active voice, then use the passive voice, but limit the occurrences.

Topic 3 | Indefinite pronouns
Rule | Restrict the use of indefinite pronouns such as it, this, and those, especially at the beginning of sentences.
Example | The Menu Editor is a configuration tool for the Main Menu. It is very useful in setting your system to your system requirements.
Rewrite | The Menu Editor is a configuration tool for the Main Menu. The Menu Editor provides a useful way to set your system requirements.
Exceptions | Very restricted usage only.

Topic 4 | Future tense
Rule | Use the present tense in your writing wherever you can. Do not use the future tense, or future passive tenses.
Example 1 | In the menu tree you will notice that there are two main menu lists.
Rewrite 1 | The menu tree contains two main menu lists.
Example 2 | In the menu tree you will have noticed that there are two main menu lists.
Rewrite 2 | The menu tree contains two main menu lists.
Exceptions | Restrict the use of the future tense to only those circumstances that will happen at some future point in time, such as next year.

Topic 5 | There is, there are
Rule | The terms there is and there are are ambiguous. Do not use these terms.
Example | In the menu tree there are two main menu lists.
Rewrite | The menu tree contains two main menu lists.
Exceptions | Limit your use of these terms. Test your text to see if you can phrase the sentence with a more definite verb.

Topic 6 | Sentence length
Rule | See fundamentals-2.
Example | If you would like to place a menu item onto the panel, you can drag and drop from the menu to the panel and it will place a launcher there with all the appropriate properties set for you.
Rewrite | You can drag a menu item from the menu to the panel. The drag action places a launcher on the panel with all the appropriate properties set.
Exceptions | Legal statements.

Topic 7 | How to introduce lists and procedures
Rule | See infodesign-12.
Example | In the Properties dialog select:
Rewrite | In the Properties dialog select the following parameters:
Exceptions | Single nouns in front of a colon are acceptable, as opposed to a sentence fragment. For example, if the preceding paragraph discusses parameters, you can introduce the list of parameters in the following way: Parameters: Also note the use of the gerund following in this context.

Topic 8 | Parentheses
Rule | Use parentheses to introduce abbreviations that you will use later, such as GNOME Documentation Project (GDP). Do not use parentheses to provide explanations.
Example | The theme files should be in a tar.gz or .tgz format (otherwise known as a tarball).
Rewrite | The theme files are usually in a tar.gz or .tgz archive file, known as a tarball.
Exception | None.

Topic 9 | Rank of structures within a sentence
Rule | Repeat noun modifiers to make structures equal in rank in a sentence.
Example | You can start applications from panel menus or objects.
Rewrite | You can start applications from panel menus or panel objects.
Exception | None.

Topic 10 | Semicolons
Rule | See the entry for Semicolons in grammar.
Example | The first option in the dialog is selected; all the other options are unselected.
Rewrite | The first option in the dialog is selected. All the other options are unselected.
Exception | None.

Topic 11 | Personal pronouns
Rule | Do not use personal pronouns other than you. See also the entry for Gender in grammar.
Example | We recommend this method of moving a symbolic link.
Rewrite | Use this method to move a symbolic link.
Exception | None.

Topic 12 | May
Rule | Replace may with can or might.
Example | These settings may be accessed from the GMC Preferences dialog. You may launch this dialog by selecting the Preferences item from the Settings menu.
Rewrite | You can access these settings from the GMC Preferences dialog. To launch this dialog select the Preferences item from the Settings menu.
Exception | Use may only when you grant permission to do something.

Topic 13 | Possessive apostrophe 's, Saxon Genitive. See language.
Rule | Replace the genitive construction with an of structure. See also the entry for Apostrophe in grammar.
Example | You can configure a drawer's properties by right-clicking on the drawer's icon and selecting Properties.
Rewrite | To configure the properties of a drawer, right-click on the drawer and select Properties.
Exception | Use the genitive construction for named individuals, for example: Bob's book.

Topic 14 | Contractions
Rule | Replace contractions with the relevant complete words. Especially avoid the 's contraction for is and has. Translators can confuse these contractions with each other, or with the Saxon genitive or even with plurals. See also the entries for Apostrophe and Contractions in grammar.
Example | If you're new to GNOME...
Rewrite | If you are new to GNOME...
Exception | Only use a contraction if you cannot find a reasonable alternative.

Topic 15 | Exotic tenses
Rule | Write in the present tense. Avoid conditional phrases and past tenses.
Example | If you are missing any drives that might have been added to your machine, you may right mouse click on the desktop and choose...
Rewrite | If any drives are missing from your machine, right-click on the desktop and choose...
Exception | None.

Topic 16 | Gender-specific references
Rule | See fundamentals-9.
Example | Tell the user to reset his password.
Rewrite | Tell the users to reset their passwords.
Exception | None.

Topic 17 | Articles
Rule | Do not omit articles in prose.
Example | Open Main Menu and select item.
Rewrite | Open the Main Menu and select an item.
Exception | None.

Topic 18 | When, if
Rule | Use when for an inevitable event. Use if for a conditional event.
Example 1 | When the prompt is displayed. This sentence implies that the prompt is definitely displayed. The only question is when the prompt is displayed.
Example 2 | If the prompt is displayed. The sentence says that the prompt might, or might not, be displayed.
Exception | None.

Topic 19 | Colloquial language
Rule | See fundamentals-3.
Example | The Modem Lights Applet is a handy applet that will start your dialup connection.
Rewrite | The Modem Lights applet starts your dialup connection.
Exception | None.

Topic 20 | Conjoined sentences
Rule | Do not join sentences with conjunctions such as and or so. Instead, create two sentences.
Example | At the time of publication of this manual there were not any applications that offer full session management for your data, so until there are some and you are aware of their capabilities you should not rely on session management to save your application.
Rewrite | At the time of publication of this manual there were not any applications that offer full session management for your data. Do not rely on session management to save your session, until you have a reliable session-management application.
Exception | Use conjoined sentence structures only for short sentences.

## Terminology Considerations for Translation

Translators or readers can sometimes misinterpret your text, for example if you use synonyms for the same concept. Use the following guidelines to avoid common areas of misinterpretation:

- Use terms that are defined in the American Heritage Dictionary.

- Use terms that are defined in wordlist.

- Define new terms the first time that they appear in text. If your manual has a glossary, then you should include the new terms in the glossary. You should also include the new term in wordlist. Contact Eugene O'Connor docs@gnome.org with your suggestions for new terms.

- Do not use terms that are jargon or slang.

- Do not use terms that have several different meanings.

- Use your defined terms consistently throughout your documentation. Do not use synonyms.

- Do not use the same word for several different meanings.

- Ensure that your spelling is correct. Use the American Heritage Dictionary as your standard for spelling. Use your spellchecker. Work with a copy editor whenever possible.

- Use consistent uppercase and lowercase rules throughout your documentation.

- Avoid general adjectives that a translator can interpret in several ways. For example, the user-friendly GNOME Desktop. A translator has to decide whether GNOME is user-friendly, or the Desktop.