[en] Guidelines/rules for messages

@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?
1 Like

Thanks, I like these suggestions. About the “did you mean …” phrase: I think it’s a good fit when a) it’s clear the error is just a simple typo and no other explanation is given because it doesn’t seem necessary. b) we need special emphasis that the rule might be wrong, in addition to a carefully worded explanation ("… usually …", “… consider using …”). What do you think, is that a useful guideline?

@dnaber, yes, it is a useful guideline. Thanks for clarifying.

And to confirm: “Did you mean” is not usually necesary if there is another explanation. We just put the suggestion either in the message, if it fits there, or after the message.

Yes, that’s what I meant. There’s also no reason to spend much time trying to build a sentence where the suggestion is in the <message>. It’s totally fine if it’s after the <message> in its own XML element.