For our writing style, if an action is successful, tell it to the user in the most succinct way possible. Don’t be afraid to add a little personality here.
- Don’t: Successfully changed 1,234 schema titles in NPI.
- Do: 1,234 titles changed. Nice job!
If an action is not successful, tell the it to the user succinctly, and if possible provide a quick way to remedy the situation. If the error happened because of something on our end, we should tell the user that and take ownership.
Don’t be quirky here. This could be a stressful time for the user. We should respect that. In this case, we can’t be delightfully quirky. Any quirkiness that we add can’t be really truly delightful because of the situation.
Avoid negative words like: Oops, Error, Failed, Problem, Invalid, Wrong, and Prohibited. These words make the user feel as though they've made a mistake. Instead focus on how they can fix the error. We should be reassuring not negative
For user errors
- Don’t: Oops! You didn’t provide a valid email, so we couldn’t email your colleagues!
- Do: The email that you provided isn’t in our system. Change email?
For Alation errors
- Don’t: Sorry! We couldn’t email your colleagues.
- Do: We couldn’t email your colleagues because something went wrong on our end. Our team has been notified and we’re working on a fix. Sorry for the inconvenience.
- December 9, 2016 - Promoted to alpha
- August 10, 2016 - Updated Error message wording to stress being reassuring more
Thanks to these folks who've contributed greatly to these guidelines