Check out these excellent writing tips from IBM on how to “Globalize your On Demand Business”
The following style suggestions can help ensure your information is clear for all types of audiences:
- Write sentences as short and simple as possible. Try to keep sentences to 25 words or less.
- Make sure that lists are complete and can stand by themselves.
- Use a complete sentence to introduce a list.
- Make list items complete sentences or complete phrases.
- Make list items parallel in structure.
- Avoid slang, jargon, humor, sarcasm, colloquialisms, and metaphors. For example, use “estimate” instead of “in the ballpark.”
- Be succinct. Eliminate unnecessary text and redundancies.
- Do not use Latin abbreviations.
- Avoid negative constructions. For example, use “It is like the previous request” rather than “It is not unlike the previous request.” Or, use “Log on again to reconnect” instead of “You cannot reconnect without logging on again.”
- Avoid ambiguity.
- Use an appropriate and consistent tone.
- Choose examples that are appropriate for the intended audience.
Appropriate grammar enables easier, more accurate translations and enhances audience understanding:
- Write in active voice whenever possible and use the present tense.
- Avoid the infinitive (to create), present participle (creating), and past participle (created) forms of verbs in the beginning of sentences. These verbs are less direct, and the subject of the clause is not always obvious. Completing steps could mean “When you complete the steps” or “Because you complete the steps.”
- Avoid noun strings. Limit compound phrases to no more than three words. When a compound phrase is used, be sure that it has only one meaning and that the phrase is used consistently.
- Make the subject of a verb phrase clear. Avoid complex sentences where several adverbs or other modifiers are used. If you use complex sentences, it is particularly important to include whatever words are necessary to make the subject clear. Do not omit the word “that” from clauses. The use of the conjunction “that,” while technically optional in some sentences, is never wrong and makes the sentence easier to translate and clearer for users whose primary language is not English. For example, use “Verify that your directory service is working” rather than “Verify your directory service is working.”
- Avoid using words in multiple grammatical categories (verb, noun, adjective). In English, many words can change their grammatical category. In most other languages, the same word cannot be a verb, a noun, and an adjective. (Use “during the restore operation” instead of “during the restore.”)
- Avoid ambiguous pronoun references where the pronoun can possibly refer to more than one antecedent. For example, in the statement “If there is prompt text for the completed field, it does not change,” it is not clear if the “prompt text” does not change or the “completed field” does not change.
- Use simple and clear coordination so the reader can tell what the relationships are between the elements of a sentence. For example, “the file or result field definition” could mean: “The result-field definition or the file,” “The file definition or the result-field definition,” “The file-field definition or the result-field definition,” “The definition of the file or of the result field,” or “The field definition of the file or of the result.”
- Ensure the elements of a sentence are parallel. Words, phrases, and clauses should be grammatically equal. Use “network management, databases, and application programs” rather than “network management, databases, and writing application programs.”
- Avoid using too many prepositions in a sentence, but do not omit prepositions or articles that are necessary. The sentence “This is a list of the current status of all event monitors for this process” could be rewritten to “This lists the current status of all event monitors for this process.”
- Do not use the dash parenthetically (as in “It is at this point – the start point – that designers and writers meet”). Translators, however, accept the dash being used to show an extension of a sentence (as in “The most important people in IBM are the customers – they pay us”).