General Messages

Guidelines | Examples of Good and Bad Error Messages | Technical Notes

If the system detects an error, it displays a message either in the status bar or in a dialog box, depending on the type of error. The message should state the problem and offer an solution to enable the user to proceed without outside assistance.

Figure 1: The most important guidelines for messages.

Guidelines

Precise and Unambiguous

Be as precise as possible.

Messages should describe the situation which has occurred as unambiguously as possible.

Support

Offer the user direct support for the error recovery. Do not just state the problem, but rather indicate what needs to be done (see examples of Messages Prompting The User). If this is not possible, use a positive tone to explain the problem as precisely as possible. Additional support, if available, can be provided in parentheses.

Formulation

Adopt a courteous and positive tone, rather than being supercilious or condemning the user. Avoid the use of vague or judgemental words such as "may", "must", "should", "wrong", "insufficient", "incomplete", "not allowed", and so on.

User-Centered

Be specific and address the problem in the user's terms. Also avoid error messages which contain technical descriptions or explanations.

Syntactic Structure

Use clear and simple syntax and only write complete phrases (this ensures better understanding and also facilitates any translation process). Articles can be omitted; a verb (at least "is" or "are"), however, should always be present. Use the present tense, if possible.

Uppercase/Lowercase

Use normal upper and lower case conventions. Do not use upper case or spaced text for the purposes of emphasis. Exception: uppercase for report names, transaction codes, table names, file names.

Language

Be consistent in your use of language; do not mix different languages.

Punctuation

Do not conclude the message with a period or with an exclamation mark. Suggestions for the error correction can be given in parentheses. Always leave a space after a period and never before one.

Special Characters

Do not use special characters such as < >, as they will not necessarily be known to the user; value specifications such as % can be used, however. Messages are not to be introduced or concluded with asterisks (***). Never put field names, report names and table names in quotation marks.

Abbreviations

Follow the guidelines for abbreviations (see Abbreviations) and be consistent with the use of abbreviations.

Examples of Good and Bad Error Messages

The following sections list examples of bad and reformulated error messages (without comments) to illustrate the above-mentioned guidelines.

Messages Which can be Formulated More Specifically

Bad: Key & not in table &
Good: Distribution channel & is not expected (Please check entry)
Bad: The cursor is not placed on a line which can be selected
Good: For the selection, please position the cursor on a line of the table
Bad: Release order specifications incomplete
Good: Please complete release order specifications by specifying order type, distribution channel
Bad: List was not completely processed
Good: List process cancelled at system limit (99 pages)

Messages Formulated Less Ambiguously

Bad: The line & & & & is not in table 134
Good: The combination of lines input is not valid

Note: It would be better to explain this message in detail in a dialog box. Or it is given in the short text as above, and the reference to the individual entry fields then appears in the long text.

Bad: Entries incomplete
Good: Please complete entries
Bad: No change
Good: Entries were not copied, as they already exist

Note: It is important to formulate the message from the point of view of the user and not from the system's perspective.

User Prompt Messages

Bad: Deletion flag incorrect, only 'J', 'S', ' ' allowed
Good: Please enter 'J', 'S' or ' ' as deletion flags
Bad: Postal code not entered or has incorrect length
Good: Please enter postal code in defined length
Bad: Percentage rate must be smaller than 100%
Good: Please enter percentage rate between 0 and 100
Bad: No items selected
Good: Please select items in the list first
Bad: Release date entered incorrectly
Good: Please enter the release date in the form MM.DD.YYYY

Technical Notes

Messages like all message texts with language indicator and MESSAGE ID are maintained using transaction SE91. Relevant field contents can be inserted into the short text by using the placeholder "&". The current field contents are then appended to the MESSAGE statement with WITH in the order in which they are to be inserted into the short text. The MESSAGE ID must be specified at the beginning of the module pool in the PROGRAM statement:

PROGRAM <name> MESSAGE-ID <ID>

By using WITH, you can append even more field contents to the MESSAGE statement than the number of placeholders contained in the short text, because the more detailed long text can require this. All field contents following WITH can be inserted into the long text in any sequence using "&V1&", "&V2&", "&V3&" ... By means of the number, a reference is made to the corresponding field entry of the field contents listed behind WITH.

Messages in the ABAP/4 are issued in the module pool by using the MESSAGE statement.

top