UX/Improve User Experience of Messaging in Horizon

Improving the UX of Messages within Horizon
NOTE: There are certain items listed in the” Message Guidelines -- An Initial Proposal” section that Horizon does follow today, the Guidelines are meant to be a list to follow, not just to point out the gaps.

For reference, there have been a few blueprints that we’ve talked about in this space:

 * https://blueprints.launchpad.net/horizon/+spec/improve-error-message-details-for-usability
 * https://blueprints.launchpad.net/horizon/+spec/horizon-notifications
 * https://blueprints.launchpad.net/horizon/+spec/show-image-minimal-requirement-when-creating-instance

Issues with Current Approach
In querying for “error message(s)” in Horizon, the query returned 49 bugs that were in various stages -- about 22 of them were being addressed (in progress or fix committed). This is a small subset of the list:
 * https://bugs.launchpad.net/horizon/+bug/1281679
 * https://bugs.launchpad.net/horizon/+bug/1155008
 * https://bugs.launchpad.net/horizon/+bug/1270984
 * https://bugs.launchpad.net/horizon/+bug/1274146
 * https://bugs.launchpad.net/horizon/+bug/1274234
 * https://bugs.launchpad.net/horizon/+bug/1275043
 * https://bugs.launchpad.net/horizon/+bug/1282232
 * https://bugs.launchpad.net/horizon/+bug/970693
 * https://bugs.launchpad.net/horizon/+bug/1018253
 * https://bugs.launchpad.net/horizon/+bug/1179607
 * https://bugs.launchpad.net/horizon/+bug/1261485
 * https://bugs.launchpad.net/horizon/+bug/1223361
 * https://bugs.launchpad.net/horizon/+bug/1237711
 * https://bugs.launchpad.net/horizon/+bug/1270817
 * https://bugs.launchpad.net/horizon/+bug/1276696
 * https://bugs.launchpad.net/horizon/+bug/1278482
 * https://bugs.launchpad.net/horizon/+bug/1285147
 * https://bugs.launchpad.net/horizon/+bug/1296430
 * https://bugs.launchpad.net/horizon/+bug/1283248
 * https://bugs.launchpad.net/horizon/+bug/1270738

The issues seem to fall into the following categories:

 * 1) Lack of human readable information to understand what to do next
 * 2) Unclear or vague error message
 * 3) Lack of error message when an error occurs
 * 4) Error messages are sometimes inconsistent with what is seen in CLI
 * 5) Lack of or no guidance provided to the user on how to resolve the error

They seem to pertain to informational, warning, and error messages.

NOTE: There are also many bugs for services outside Horizon that face similar challenges that can benefit from this effort.

Message Guidelines -- An Initial Proposal
A message delivers information about an action or condition and optionally asks the user to confirm the situation. The scope of this document is limited to Error, Informational, and Warning messages.

The following is a suggested set of guidelines for the following types of messages:

 * Error message -- this is used to report a problem and indicates to the user that some action must be taken before the System or Service can continue. E.g. an error message might indicate the user lacks permission to execute a requested action or show a problem found after a user chooses an action in a menu, dialog, or wizard.
 * Informational message -- it’s used to guide users through a workflow or convey a pertinent message. It can be used to provide the results of an action or indicate that the System or Service is in the process of performing some kind of action.
 * Warning message -- When you want to make users aware of a potentially harmful or problematic condition, give them a warning.

The solution should be something that ultimately focuses on a few things when it comes to giving error messages to our users:

 * 1) Continuing to place error messages in a visible area for the end user
 * 2) Giving enough human readable information to understand what to do next
 * 3) Ensuring every error will result in notifying the user
 * 4) Consistency of messages between API, CLI, and UI

Visibility:

 * Ensure the message is prominent.

Human Readable:

 * Whenever possible, provide names, locations, objects, and values of the objects involved.
 * Indicate what condition has occurred and which service or component is involved (if relevant).
 * If the application displays a message generated by another application (e.g. a pass-through message), include the name of the other application.
 * If the message was generated by an application (as opposed to a user), indicate the application name and/or relevant action.
 * Be concise, specific, and address the user as "you".
 * Don't blame the user.
 * Use active voice. Active voice makes writing more simple and direct.
 * Avoid the words "please" and "sorry."
 * Write complete sentences and use ending punctuation.
 * Make the object plural when the user selects more than one object.
 * Use language that is familiar to the user.
 * Do not use contractions. Contractions pose a problem for translators and for people who are not native English speakers.
 * Original: Can't connect to Horizon
 * Rewrite: Cannot connect to Horizon

Make sure the user knows where to go from here:

 * State the specific error or warning and recommendation for how the user can correct the error.
 * If a problem exists, state why the problem occurred, and how to remedy the situation, even if the remedy is "Contact your Administrator."
 * If the recommendation is a series of tasks the user needs to perform,state the instructions in the correct sequence.
 * Avoid messages that are too general and do not highlight the problem in a way that makes sense in the context in which the message is displayed.
 * Ensure that users can copy the text in the message window and paste it elsewhere.

Consistency:

 * Ensure consistent messages between UI, CLI, and API.
 * Use same name as the menu, action, or command button that opened the message box.
 * Tips and Best Practices for Forms Specifically:
 * It’s important to be proactive and stop users before they submit a form with an error when possible. If they do submit the form with an error, be sure to do the following:
 * Make it clear that something is wrong.
 * Show the user which field (or fields) are wrong in form errors.
 * Display error messages that help users get back on track.
 * Save what the user has entered—both good and bad so they do not have to repeat data entry.

Tips and Best Practices for Visualizations Specifically:

 * We should be sure to include text explaining the error that the visualization is showing, whether this is near the visualization or on hover. Allowing the user to get more information on * why they are seeing an error and how to troubleshoot it in clear text is important for them to be able to choose what to do next.