\\ home
\\ resources
\\ events
\\ about

By Susan Harkus

Effective communication is the objective of all documentation, whether the documentation is technical or non-technical, and the communication objective must not be constrained by unrealistic writing guidelines.

The guidelines in this document preserve the flexibility that enables a writer to present information to the user in a format and in a structure that facilitate understanding. They are based on the principle that writing for translation assists the human translator as well as the translation software.

The guidelines describe a writing approach that:

• acknowledges good writing practices
• optimises the parsing of the source by the translation software
• specifies formatting that is recommended for particular translation software
• employs the features of the translation software
• adopts mitigation strategies for content that has locale dependencies

A checklist of the guidelines is included at the end of this document. The PowerPoint presentation accompanying this document can be downloaded here (136K, PPT). The slide notes contain the full presentation script.

Follow good writing practices

Good writing practices improve the readability of documentation. They produce documents that are easy to understand, and almost always easier to translate.

Despite the individual writing preferences of technical communicators, most references acknowledge a set of rules that can be defined as "good writing practices". Selected reminders are listed below under the two headings, Style, and Format and Punctuation.

Style

• Write clearly. Use simple sentence structures. A sentence need not be short but must provide progressive cognitive closure.
• Limit the number of nouns that qualify a noun. Never use more than three noun qualifiers, and in almost every case, add groups of noun qualifiers to the dictionary of the translation software.
• Repeat a noun instead of using a backward-pointing pronoun, such as "it", "they," "this" or "these". Pronouns can frequently impede reading because the reader has to mentally associate a pronoun with its antecedent. If the association is not immediately clear, the reader often has to reread the preceding sentence to establish the context of the pronoun.
• Put phrases as close as possible to the nouns that they modify. Rewrite a sentence rather than create an orphan phrase or clause.
• Avoid an informal style. Use a semi-formal tone and avoid rhetorical questions.

Format and punctuation

• Separate subordinate phrases and clauses from the main clause by commas. For example, this sentence includes an example of a subordinate phrase. If you begin a sentence with a conditional clause, separate the conditional clause from the principal clause with a comma.
• Hyphenate word phrases that modify other words. For example, gather customer-specific requirements.
• Always use commas correctly in coordinate phrases and clauses. For example, a comma is required before an "and" or an "or", if the next phrase or clause includes a coordinating conjunction. Compare "the apples, the drink, and the bread and butter" and "the apples, the drink and the bread".

Write to optimise translation output

Translation software performs two discrete tasks.

1. Parse the source text.
2. Translate the parsed text into the target language.

The success of both operations depends primarily on the power and the scope of the translation software. However, some writing practices improve the efficiency of the parsing operation, and some practices improve the translation itself.

Improve parsing

• Use an article or a descriptor to clarify the part of speech of a word. Words such as "a" and "the", provide syntax cues to translation software, as well as to human translators.
• Include relative pronouns even when they are not required in English. For example, "the car that he bought" rather than "the car he bought".
• Write list items as complete clauses or complete sentences.
• Include the article with each item in a list of nouns or noun phrases.
• Avoid phrasal verbs, such as "set up" or "shut down". Use a single word alternative. Most commercial translation products are unable to analyse phrasal verbs, except for the most common verbs, such as "wait for". If you have to use a phrasal verb to retain a natural expression in your source, review the translation of the verb during the post-translation edit.

Improve translation

• Minimise ambiguity. Avoid homographs. If an English word has several meanings, use the word consistently with one meaning, and use an alternate English word to express other meanings. For example, use "right" as the opposite to "left", and use "correct", not "right" as the opposite to "wrong".
• Use words with their primary dictionary meaning. If you choose not to use a word with its primary meaning, be sure to add the word to the dictionary of the translation software.

Use formats recognised by the translation software

Most translation products will use formatting cues for syntactical parsing. The following guidelines reflect the recommendations of the Systran product manual. Modify the guidelines to reflect the requirements of the software that you purchase.

• Add two spaces after a full stop or a colon. Add one space after a comma or semicolon.
• Use a combination of punctuation, capitalisation and font to identify a name such as an object name or a function name. Do not rely on the font alone to distinguish the name. For example, "Choose the option, Exit", rather than "Choose the Exit option."
• Do not use a dash as a punctuation mark. Reserve the dash for hyphenating multi-word adjectives.
• Avoid using a slash (/) for alternate values. For example, write "your customer or supplier" not "your customer/supplier".
• Use parentheses sparingly, and only when the enclosed material is independent of the structure of the surrounding words.

Product recommendations that are not appropriate

Some product recommendations will not suit your corporate documentation style. For example, Systran suggests that you add two carriage returns after titles and headings, and also that you insert a comma or semicolon. before the coordinating conjunction, "and".

If you do not follow every recommendation made by the product supplier, additional translation errors may be incurred. However, the readability of your source is very important and unusual punctuation can easily distract readers. Your objective is clear communication and you must decide whether you will follow every product recommendation

Identify and exploit product features

All translation products have features that can be used to optimise the translation output. Identify the features and determine how you will apply them in your writing.

For example, Systran provides a mechanism for tagging text, such as sample code, that should not be translated. The tags can be inserted as hidden text, before and after the protected words, so that they are not printed or displayed online.

$AB <title> $ABX
Such is life
$AB </title> $ABX

Adopt mitigation strategies for locale-dependent content

Localisation effort can be reduced if technical communicators use mitigation strategies for information that varies between locales.

By applying a mitigation strategy, the writer can

• eliminate a locale dependency from the text
• reduce the number of localisation changes that must be made
• identify locale-dependent content that must be updated during the localisation edit

Examples

1. Eliminate a locale dependency related to temperature, by providing the alternative measurement form in brackets.

2. Reduce the number of changes to a currency example, by including well-known currencies as well as the currency of the source language. When the currency example is localised, only the local currency will need to be changed.

3. If locale dependencies persist, record the dependencies in the list of locale items. A list of mitigation strategies is included at the end of this document.

Writing checklist

Mitigation strategies for locale issues

The following table lists areas where locale differences occur and shows the strategy the writer should adopt to minimise the impact of differences.

Source: keyword, A journal for technical and scientific communicators. Vol 7, No 2 Date: June 1997

Document management strategies for localisation

As document content is developed, maintain a writing approach that will facilitate the translation task. The following table shows the document content area that presents a challenge to translation and the proposed document development strategy for supporting translation.

Source: keyword, A journal for technical and scientific communicators. Vol 7, No 2 Date: June 1997

References

Klein, F. (1997) International Technical Communication. keyword, A journal for technical and scientific communicators. Vol 7, No 2, P17-18.

McGregor, H. (1997) International Documentation. keyword, A journal for technical and scientific communicators. Vol 7, No 2, P5-11.

Ring, P. (1997) Translation of manuals and multilingual manuals. keyword, A journal for technical and scientific communicators. Vol 7, No 2, P14-16.

While Information Manager of the Australian software development company, Cards Etc, Susan Harkus developed a disciplined writing solution that makes translation software a viable part of localising the first software release. Susan presented this paper at the Australasian Online Documentation Conference being held in Brisbane, Australia, 12-14 April. Susan now works for XT3 Internet Integrator and can be reached at susan.harkus@telestra.com

back to top