openstack/openstack-manuals
Code Issues Proposed changes
openstack-manuals/doc/contributor-guide/source/ui-text-guidelines/ui-error-messages.rst
Linette 3f4a614602 [ui-content-guidelines] Text guidelines for the UI 
Adding structure and content for UI content
guidelines within the Documentation
Contributor Guide

Co-Authored-By: Gudrun Wolfgram <gmolson@us.ibm.com>
Change-Id: Ib315913a3149cc997be4e4f09fa67df626c07562
Implements: blueprint ui-content-guidelines
2016-01-28 08:13:28 -06:00

1.7 KiB
Raw Blame History

Follow UI alert guidelines

Alerts, or messages, are important to inform users about progress that they make or problems that they encounter in the user interface.

Use the following alert types:

  • Success
  • Info
  • Warning
  • Danger (Error)

General alert guidelines

When writing alerts, follow these rules:

  • Be courteous and do not blame the user
  • Use present tense to describe conditions that currently exist, or use past tense to describe a specific event that occurred in the past
  • Keep sentences short but helpful
  • Adhere to the guidelines in the stg_writing_style section

Alert structure for new danger (error) conditions

A danger alert, or error message, should help the user resolve the problem quickly so that they can continue making progress. Do not include an error if you can avoid publishing the alert by enhancing the code.

  1. State the problem clearly and briefly.
  2. If appropriate, explain why the user encountered the error.
  3. If possible, tell the user how to fix the problem. If further information is needed, consider whether the documentation should be enhanced.

Note

API returns might not be specific enough to adhere to these structure guidelines. Be as explicit as you can in stating the problem and resolution.

Alert examples

Success
  • Successfully created key pair %(name)s.
  • Image successfully updated.
Info
  • Updating volume snapshot "%s"
  • Creating volume "%s"
Warning
  • Policy check failed.
  • Insufficient privilege level exists to view user information.
Danger
  • Unable to create the volume.
  • Unable to retrieve the image.