@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 https://www.ldoceonline.com/dictionary/over 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.
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?