Write Good Error Messages

"Cannot create entity X", "Connection to service Y failed", "Cannot read file Z".
These are typical error messages seen in many systems. And they are extremely bad.

So what's wrong with these messages? They are not actionable, they don't have any details what exactly went wrong (only for connection issue I can easily generate up to 10 reasons), they don't explain users or support engineers what to do next.

Good error message should:
- Be actionable
- Be detailed and clear
- Deliver the best user experience
- Enable users to help themselves
- Reduce support workload
- Speed up issue resolution

Google has a special chapter in their technical writing course about how to write good error messages. So let's check their recommendations:
✏️ Don't fail silently.  Failing to report errors is unacceptable. Assume that humans will make mistakes using your software. Try to minimize ways for people to misuse your software, but assume that you can't completely eliminate that.
✏️ Have a common style guide. Examples: Google API Error Handling, Go Error Handling
✏️ Do not swallow the root cause. Generic messages like "Server error" don’t help users understand or fix the issue.
✏️ Fail fast. Report errors as soon as they occur. Raising them later significantly increases debugging costs.
✏️ Identify the cause. Clearly explain what went wrong. Help users understand requirements and constraints. Be specific. Don't assume that users know the limitations of your system.
✏️ Explain how to fix the problem. Create actionable error messages. After explaining the cause of the problem, explain how to resolve it.

Example:
❌ Invalid input.
✅ Enter the pathname of a Windows executable file. An executable file ordinarily ends with the .exe suffix. For example: C:\Program Files\Custom\AppName.exe

Take time to train your team to write good error messages, it improves user experience, reduces support costs and speed up problem resolution.

#engineering #documentation