Tuesday Sep 27, 2011

How to Write Effective Application Error Messages for Users

Whenever I’m asked by technical writers how they should write a “frontend” or a “backend” error message I’m reminded of the old Kerryman joke with the “I wouldn't start from here” punchline (this joke may have been localized for your region).

Starting the error message design process with a frontend or backend categorization is not useful from a user experience perspective. Users don't care for such a distinction. All users care about is how effectively the application messages communicate with users as they do their work!

It’s tough deciding on what a “frontend” error message is, anyway. Is it a client-side validation concept? Maybe they're ADF Faces validator and converter messages?

Hardly, as these error message are visually indistinguishable from other ADF af:messages validation on editable components that require a push of data to the server for validation, and can coded as business rule exceptions deep down in the model layer.

These error messages can also be shown on ADF page components that are then outlined in red, along with a note window with the message and navigation buttons to move between components showing exceptions.

These messages then roll up to a page-level list that includes a hyperlink to the name of the component if the user chooses to address all the component-level errors together. So, that consideration doesn't work either.

ADF messages could also be page-level popups, or inline on the page, and used for messages that don't reference editable fields at all, for complex business rule validation or for UI rules such as unsaved changes, and so on.

And then “backend” error messages, what are they, exactly? Are they all diagnostic logs triggered by the supportability framework when an incident is raised? They could be text-based output logs for sure, but they could be presented in custom ADF message dialogs too. These messages could also use user interfaces (UIs) designed by product teams for third-party application or web services integrations, for errors (usually from the FND messages dictionary) thrown by the execution of PL/SQL or other programs, and so on.

So, this frontend versus backend categorization is problematic as a decision-making concept. Instead, knowing why the message appears (the validation or UI rules fired up in response to user or application activity), and what the raising technology offers in terms of visual display and output, lets you know how to phrase the error message accordingly.

For example:


  • A decision about who (or what) was acting, and who needs to act in response, lets the writer make a decision about the use of active or passive voice in the message text.
  • Knowing if the exception is from an ADF component validation means writers don't need to tell the user which UI component has an issue or how to get there. The component is highlighted in red and the message is presented beside it along with navigation buttons to other components with errors. The name of the component is shown in the page-level list as a clickable link.


  • If it is page-level business rule message dialog not using component-level validation, then the writer may need to explicitly tell the user which components need redress, where, and how.
  • If the message is in a long text output format, writers will need to compose the text in a way that allows for easy online reading, and so on.

Knowing this information also enables writers to discover if ADF Faces provides a message natively, out of the box (navigation, validators, converters, missing values, and so on), saving the writing of a new one.

For a more useful starting point consider to a superior error messaging UX, maybe answer the following questions and then apply error message text composition basics about writing cause and action using the appropriate style, grammar and terminology:


  • Is the exception the result of validating ADF editable components on a page?
  • Is the exception the result a navigation action between ADF pages?
  • Is the exception by the result of validating business rules at a page-or task-level action on ADF pages?
  • Is the exception the result of a process? Does the result of that process need to be in a printable or readable output file and/or need to be indicated elsewhere as a message dialog or even a notification?
  • Is the exception the result of a third-party application or web service integration that requires a custom designed UI?
  • Who or what is acting to make this message appear, and who or what needs to act in response, and how?

Very likely no one person in the development team will know all the answers, so writers and developers must work collaboratively to find out the answers before the message text is written.

Sunday May 08, 2011

Stand Up for Comics

Mention comics as a form of user assistance and you might think it's some kind of exercise in comedy. However, as pointed out by Rebekah Sedaca in her super article, comics are not just for laughs. Over the past couple of years there's been a huge interest in the use of comics as UA. How encouraging to see comics guru and evangelist Scott McCloud (@scottmccloud) as keynote speaker at the CMS DITA North America 2011 conference, an indicator of how seriously comics are now being taken by information development professionals.

Comics are an important form of visual communication, the possibilities of which are often underplayed by some in the UA community (usually because they mistakenly believe you need special skills to create them). Comics offer a graphically powerful and meaningful way to tell users about new features, best practices, concepts (see this great SlideShare presentation by Kevin Cheng and Jane Jao of Yahoo!), policies, and more. Alan J. Porter (@4JsGroup) offers a useful plain language definition for this form of communication: A graphic medium in which images are utilized in order to convey a sequential narrative. Importantly, the comic also conveys its message in a way that readers will recognize and relate to on a different level than other forms of help.

Increasingly, we're learning that effective UA must be affective. The UA must not only be contextual and relevant to the reader's task, representing real world examples, but it must strike a chord with them emotionally and personally. There are important returns when that happens: increased transfer of information, learning, and a great way to reinforce corporate culture, nurture enterprise and branding loyalty, and other benefits. Comics are one such form of UA.

Comics are, as Kevin Cheng says, a "universal language", a true user-centered form of communication design that can be classed as another form of "affective user assistance" as explained by Ellis Pratt (@ellispratt) of Cherryleaf in this great YouTube video about documentation as an emotional experience for users from TCUK 2010. Don Norman would be proud!

There are plenty of different examples of comics as UA that I could point out to you. You're probably familiar with the Google Chrome comic (adapted for Google by Scott McCloud). As Scott explained in his CMS DITA keynote the comic was  "amplification by simplification." Engineers at Google really wanted people to understand their work, rather than be distracted by media focus on the corporation.

Words by the Google Chrome team, comics adaptation by Scott McCloud. Image licensed under creative commons Google.com

Words by the Google Chrome team, comics adaptation by Scott McCloud. Image licensed under creative commons Google.com

Or perhaps you've seen the Oatmeal's use of comics to explain a superior UX for shopping carts? But, how about this fine manga ( 漫画) example tackling the area of RDBMS?

Copyright. The Manga Guide to Databases (Paperback) by Mana Takahashi, Shoko Azuma

Image copyright acknowledged from amazon.com for The Manga Guide to Databases (Paperback) by Mana Takahashi, Shoko Azuma

Who'd a thunk? (Japanese language version is here - h/t @taksasak.) Thanks to Debra Lilley(@debralilley) for that one.

The comics approach can also offer opportunities for combinations with other forms of information. In come cases we've seen customers and partners combine them with other UA formats such as UPK demos, and I just love this er, non-Oracle example of a cartoon/video delivery.

By the way, you don't need special skills to create comics for user assistance. If you're interested in giving comics a test run yourself, check out the Visio template distributed by Rebekah Sedaca or the http://www.makebeliefscomix.com/ website. Give it a shot. Remember, comics can make you a better communicator.

About

Oracle applications user experience (UX) assistance. UX and development outreach of all sorts to the apps community, helping to design and deliver usable apps.

Profile

Ultan Ó Broin. Director, Global Applications User Experience, Oracle Corporation. On Twitter: @ultan

See my other Oracle blog about product globalization too: Not Lost in Translation

Interests: User experience (UX), user centered design, design patterns, tailoring, BYOD, dev relations, language quality, mobile apps, Oracle FMW and ADF, and a lot more.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today