Details
-
Enhancement
-
Resolution: Unresolved
-
Major
-
None
-
None
-
None
-
Documentation (Ref Guide, User Guide, etc.)
-
undefined
Description
With the mechanism in place to generate HTML reports of log messages and "Description" annotations, next step is to add descriptions with additional detail and troubleshooting information where applicable.
As a rule each description should be two or three lines of text that:
- Explain what happened and why in more detail. The first part of the description provides additional information around the cause of the error and result. "Infinispan could not start because the configuration is invalid."
- Provide user action to resolve the error. Where no user action is possible, descriptions should state that explicity with the phrase: "No user action required."
Other considerations:
- No version detail. Descriptions should be general and not contain details specific to any particular version unless the message itself is printed only for a specific version.
- No links to documentation or phrases like "Refer to x." or "See xyz." Where appropriate you can direct users to documentation with the phrase: "You can find more information in our documentation."
Follow PatternFly guidelines for error messages: https://www.patternfly.org/v4/ux-writing/error-messages/