[kde-guidelines] Styleguide: Message dialog

[Aurélien Gâteau]

Looks mostly good. Some nitpicks follow.

On Tuesday 09 July 2013 14:25:08 Heiko Tietze wrote:
> User Assistance: Disruptive messages
> * Show a modal message dialog if the processing has been reached an
> unexpected condition that needs interaction.

"has been reached" => "has reached"
> 
> http://techbase.kde.org/Projects/Usability/HIG/Messages
> 
> == Purpose ==
> If the processing has been reached an unexpected condition that needs

ditto

> interaction, a disruptive message alerts the user of a problem. Not any
> disruptive message concerns a serious problem. Sometimes, the user is just
> notified that proceeding is dangerous. A typical example is the “Save
> changes before closing?” alert box that appears when a user tries to close
> a module with modified content. The adequate presentation method for
> disruptive information is a ''modal message dialog''.
> 
> A modal dialog is a secondary window that interrupts user's current activity
> and blocks interaction until user either simply acknowledge the information
> by clicking Ok or decides how to proceed (e.g. Yes/No). Effective error
> messages inform users that a problem occurred, explain why it happened, and
> provide a solution so users can fix the problem. Users should either
> perform an action or change their behavior as the result of an error
> message. Modal dialogs are error-prone. An alert dialog that appears
> unexpectedly or which is dismissed automatically (because the user has
> developed a habit) will not protect from the dangerous action.
> 
> == Examples ==
> 
> == Guidelines ==
> * Avoid disruptive messages; workflow maintenance and, therefore, the
> prevention of errors should be the primary objective. * Use modal dialogs
> only for critical or infrequent, one-off tasks that require completion
> before continuing. Don’t use modal error message dialogs at the normal work
> flow to inform or warn the user.
> * Use
> [[Projects/Usability/HIG/MessageWidget|mesage panel]] for non-critical

"mesage panel" => "message panel"

> messages which do not require any further user interaction (typically
> dialogs with a single "OK" or "Close" button).
> * Create specific,
> actionable, user-centered error messages (Figure 60). Users should either
> perform an action or change their behavior as the result of the message.

Where is figure 60?

> * Provide only a short error message and complement it by a Details button
> that provides more a detailed explanation in the same error dialog.

> * If it makes sense for this kind of error, link from the error dialog to
> the corresponding page in the help system. Provide a Help button then.

KMessageBox does not allow adding a Help button :/
> 
> === Dialogs in general ===
> * Don’t apply dialog boxes that require the use of a scroll bar.
> * Don’t include a menu bar or status bar in dialogs.
> * Don’t display more than one owned choice dialog at a time from an owner
> choice dialog.
> 
> === Language ===
> * Messages should be:
> ** Understandable: Phrase your messages clearly, in non-technical terms and
> avoid obscure error codes.
> ** Readable: User has to be able to read the
> message in his/her own pace, think about it, understand it. Adding
> countdown timers (visible or not) and forcing user to read and understand
> the message within a few seconds is not acceptable,
> ** Specific instead of
> general: If the message is reporting a problem concerning a specific object
> or application, use the object or application name when referring to it.
> **
> Informative and constructive: Tell the user the reason for a problem and
> help on how to solve the problem.

I think this guideline is the most important one. I would put it first and add 
a bit more emphasis to it by formatting it with a numbered list:
** Informative and constructive:
1. tell the user the reason for the problem
2. provide advice on how to solve the problem

Aurélien