How to Write Effective Application Error Messages for Users
By Ultan O'Broin-Oracle on Sep 27, 2011
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.
- 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.