Best practices
Be specific
The more generic your message is, the less helpful it will be. Consider the context and make your message relevant. Create messages that are specific to each case where possible.
Use sentence case
Only the first letter of a heading or sentence should be capitalised, with the exception of product names. Sentence case improves readability, is easier to skim, and has a more conversational manner.
Use plain language and avoid jargon
Avoid internal language, uncommon acronyms or jargon. Technical terms are different than jargon and are fine to include if they are relevant and appropriate for our audience.
Never blame the user (even if they are at fault)
Some errors are the result of a direct user action. Let them know what happened without blame or accusation.
Your computer appears to be offline.
You went offline.
Apply the correct tone
Errors can be frustrating and cause confusion. Always be positive, friendly and reassuring. Match your tone to the situation. The more impact the error has the more serious and less playful your tone should be.
Anatomy
Regardless of where it appears or the length, all error messages should be made up of the same key components (where possible):
- What happened
- The cause
- How to fix it
- More details (optional)
Usage
What happened?
This is the heading or headline of your error. As it is a heading no full stop is used. Communicate the general outcome of the error and what it means for the user using plain language. In the majority of cases this sentence will be one line only.
Your variables couldn't be saved.
You do not have permission to perform this action. Please contact your Octopus administrator. Missing permission: VariableEdit.
The cause
Explaining the cause can help increase a users understanding. Remember to be concise and don't let a long winded explanation get in the way of usable information.
You don't have permission to make changes to unscoped variables.
Missing permission: VariableEdit.
How to fix it
Let the user know what they can do about the error. It should be simple and offer an actionable path forward eg "Try again" or a step by step resolution in the error message text. Provide a document link if we have a specific and descriptive article on the use case. Try to avoid generic statements such as "Contact IT support".
Please contact your Octopus administrator to request the VariableEditUnscoped permission.
Please contact your Octopus administrator.
In practice
Before
After
