Guideline B: Writing for an international audience

B1: Grammar

Grammar


Guideline B1-1


Do not omit prepositions or articles from sentences.

If you omit words, such as the and an, to store an otherwise long message into a pre-allocated space, the message can be interpreted in several ways.

Example: What does the message "Print control file list" mean?

  • Print all the files that contain controls.
  • A list of files that contain print controls.
  • Print a list of control files.
  • Print the controls and file the list.
  • Control the print and list the files.
  • Print and control a list of files.

Guideline B1-2


Avoid noun strings.

A noun string occurs when one or more nouns are used to change another noun. The noun that you are changing is so buried among the other nouns that the reader cannot determine the noun that is being changed. Noun strings usually occur when you ignore the previous guideline by omitting prepositions and articles in a sentence.

Example: What does the message " Card input" mean?

  • The input of a card.
  • The input of one or more cards.
  • The concept of card input in general.

Guideline B1-3


Write in the active voice using the present tense.

Avoid the infinitive, present participle, and past participle forms of verbs at the beginning of a sentence. These verbs are less direct, the subject of the clause is not always obvious, and they are more difficult to translate in some languages.

Verb Form Example
Infinitive to study
Present participle studying
Past participle studied

Example: What does " studying plans could be useful" mean?

  • Plans that discuss studying could be useful.
  • Studying the plans could be useful.

Guideline B1-4


Avoid using words in incorrect grammatical categories, such as using a noun or an adjective as a verb.

Example:

Bad: Do not start the restore
Better: Do not start the restore operation.

Guideline B1-5


Avoid ambiguous pronoun references.

The causes of ambiguous pronoun references are as follows:

1. The pronoun can possibly refer to more than one antecedent.

Example:

Bad: You can create a virtual database from the target file system. It consists of a set of statements that guide the utility program.
Better: You can create a virtual database from the target file system. The database consists of a set of statements that guide the utility program.

2. The antecedent is too far away from the pronoun.

Example:

Bad: The computer takes the substring in position 0-2, which was part of the String object.
Better: The computer takes the substring, which was part of the String object, in position 0-2.

3. The antecedent is implied rather than explicit.

Example:

Bad: The developers agreed to discuss the issue, but it took too long.
Better: The developers agreed to discuss the issue, but the discussion took too much time.

Guideline B1-6


Use simple and clear coordination.

Make sure the reader can understand the relationships among the elements of your sentences. Consider using a list to show these relationships.

Example:

Bad: You can use commands and options or widgets on the GUI.
Better: You can perform tasks in two ways:
- Use commands and options.
- Use the widgets on the GUI.

Another type of coordinate construction that can be troublesome for automatic analysis is gapping. This occurs, for example, when two clauses are coordinated but the verb is omitted from the second clause.

Example:

Bad: The file names are displayed in uppercase characters and the other file attributes in lowercase characters.
Better: The file names are displayed in uppercase characters, and the other file attributes are displayed in lowercase characters.

Guideline B1-7


Ensure the elements of your sentences are parallel.

Your words, phrases, and clauses should be grammatically equal.

Original If the new file has the same name as an existing file, do one of the following:
- Specify the REPLACE option, to replace the existing file
- Give the file a new name (RENAME option).
- By indicating IGNORE, stop processing the file.
Revised If the new file has the same name as an existing file, specify an option:
- REPLACE – to replace the existing file
- RENAME – to give the file a new name
- IGNORE – to stop processing the file

Contact IBM

Need assistance with your globalization questions?

Guidelines