Uploaded image for project: 'Infinispan'
  1. Infinispan
  2. ISPN-13238

Docs: Add description annotations and generate v1 HTML report for log messages

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Unresolved
    • Major
    • None
    • None
    • Documentation
    • 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/

      Attachments

        Activity

          People

            dvagnero@redhat.com Dominika Borges
            dnaro@redhat.com Donald Naro
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

              Created:
              Updated: