Developing message help
A message is any communication that is passed from the application to a user or to another application. z/OSMF uses messages to inform users of important events, such as state changes and errors that require resolution.
For the messages your application issues, use the XHTML
tagging language to create a separate help file for each message.
Include the following attributes for each message:
- message ID. Specifies a unique alphanumeric identifier
that provides a quick means to distinguish one message from others.
Use the message ID as the filename and topic title. Vendor message IDs can start with the letters J-Z; the letters A-I are reserved for IBM. The last character indicates the severity of the message, which can have one of the following values:
- I for information. Describes information or status for normal conditions and operations.
- W for warning. Alerts users to a condition that might cause problems in the future. When a warning message is displayed, users can generally continue with their tasks, but those tasks might not complete in a way that is expected.
- E for error. Alerts users to a problem that already occurred. Users or systems cannot continue their tasks.
For example, YYZR134I.
- message text. Briefly describes the problem or situation
from the user's perspective. Messages can have variables (or arguments),
which are typically numbers or placeholders that are used in a message
in place of a specific file name, command, component, or other object.
In the message text, ensure that you:
- Focus on the problem, not the error.
- Describe the problem briefly, use full sentences, and ensure that the information is accurate.
- Avoid wording that seems to blame the user.
- Do not concatenate multiple messages to create a single message.
- Make variables meaningful and unique.
- Replace variables only with proper nouns.
- Use double quotation marks around variables only when necessary.
- explanation. Expands the message text and provides more
detail. In the explanation, ensure that you:
- Explain why the message was issued.
- For error and warning messages, describe the cause of the problem (when and where the error occurred), explain the consequences of the error, and provide information to help users avoid the problem in the future if possible.
- Do not repeat the message text in the explanation section.
- Avoid using codes to build messages and resolve problems in error handling. However, if your application uses codes, describe the codes consistently in your messages and include corrective action so users do not need to look elsewhere for an explanation of the code.
- userResponse and sysprogResponse. Describes what
the user (userResponse) or system programmer and administrator (sysprogResponse)
must do to proceed, to recover from the error, or to prevent a problem.
If no response is required, enter No action is required. For
warning and error messages, a response must be provided for the system
programmer, the user, or both. In the response, ensure that you:
- Use active voice when possible.
- Provide complete and specific instructions to resolve the problem.
- Link to other information if necessary.
- Categorize the actions.
- Do not leave the response section empty.
- Ensure that wrapped, associated, and stacked messages are consistently presented.