@dnaber asked me post these guidelines/rules for how to write message text. Please give your comments/suggestions.
For information about how to write internationalized English, refer to ‘The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market’ https://support.sas.com/en/books/authors/john-kohl.html. Many of the guidelines are explained in detail in this book.
Some of the examples are from XML rules, and some are my invented examples.
-
Always use correct grammar and punctuation. If possible, use a subject-verb-object structure.
Not: If following ‘per’ nouns are often singular.
Use: Usually, after ‘per’[,] a noun is singular. -
Make the message as simple as possible. Do not include unnecessary or confusing information:
Not: When you refer to pronouns, ‘they’re’ is a contraction of …
Use: ‘they’re’ is a contraction of …
Reason: ‘They’re’ is always a contraction. -
Do not use unnecessary words:
Not: When at the start of a sentence,
Use: At the start of a sentence, -
Use a word with its basic meaning.
Not: At the start of a sentence, ‘Regards’ is used over ‘Regard’.
Use: At the start of a sentence, ‘Regards’ is used in preference to ‘Regard’.
Use: At the start of a sentence, use ‘Regards’ in preference to ‘Regard’.
Reason: Many users of LT do not know English well and can be confused by unusual meanings. The Longman Dictionary of Contemporary English is a good resource because it is designed specially for advanced learners. On over | meaning of over in Longman Dictionary of Contemporary English | LDOCE there are 16 definitions of the preposition ‘over’. The first definition is ‘above/higher’. The sixteenth definition is ‘preferring’, which is the meaning in the original message. -
Avoid gerunds/~ing:
Not: When referring to the past,
Use: When you refer to the past, -
Do not make incorrect generalizations:
Not: When verbs follow ‘was’ they are past tense, like: …
Use: In the active voice, when a verb comes after ‘was’, it is in the present tense…
Reason: With the passive voice, the verb is past participle: The window was opened by the technician. -
Be as accurate as possible (and refer to ’ Do not make incorrect generalizations’):
Not: When verbs follow ‘was’…
Use: When a verb follows ‘was’… -
Except for the most obvious errors, give a reason. (What is obvious to us is not always obvious to the reader). Include a link if possible:
Not: In this instance, the present tense verb [suggestion] must be used instead of the past tense version.
Use: After the modal verb ‘can’, use the infinitive (base form) [suggestion].
Use: After the modal verb ‘can’, use the infinitive (base form). Did you mean [suggestion]? -
Do not only make an assertion. Tell the reader what to do:
Not: ‘Keep up’ is a phrasal verb used to express a continuation, such as in the sentence: …
Use: To express a continuation, use the phrasal verb ‘keep up with’, such as in the sentence: … -
If possible, make the marked text correspond with the correction:
Message: ‘Keep up’ is a phrasal verb…
Marked text: with -
Use quote marks to identify words that would be in italics in printed text.
-
Do not omit articles.
-
Include optional ‘syntactic cues’ because they help readers (specially non-native readers) to parse the sentence.
Not: The book on the table is mine.
Use: The book that is on the table is mine. -
Put a condition first, then the consequence.
Not: You will become wet if it rains.
Use: If it rains, you will become wet. -
Put the explanation first, then the suggestion.
-
Use the Oxford comma:
Not: Did you mean ‘this’, ‘that’ or the ‘other’?
Use: Did you mean ‘this’, ‘that’, or the ‘other’? -
If an adverb or an adverbial phrase modifies a sentence, put the adverbial at the start of the sentence:
Not: You can usually use X.
Use: Usually, you can use X. -
Make sure that the first correct example contains no errors and that the first incorrect example contains only one error (the error that the rule is designed to correct). A user can see these examples.
Incorrect text that is not related to the rule correction has these problems:
- It can distract a user. Why does LT show “at last night”? Last week my teacher explained that correct English is “last night”.
- It can annoy a user and cause the user to not use LT. Worse, it can cause a user to badmouth LT. Why should anyone trust LT if the examples we show are not correct?