The Error Message I Rewrite Until a Stranger Understands It

Error messages are often overlooked during product design. Rapid development focuses on the desired outcome, leading to simple, generic error text being used. However, confusion caused by bad error messages can have significant consequences. They waste support resources, frustrate users, and ultimately damage trust in the tool. To address this, error messages must be designed as a dedicated surface area for communication.

The author now treats error text as a crucial design element and applies a strict test before shipping. This test requires a stranger with no prior knowledge of the tool to understand two things: what went wrong, and what action to take next. If a stranger cannot grasp these points, the error message must be revised, regardless of technical accuracy.

The author's approach focuses on three key components in a fixed order: what happened, why it happened, and what to do next. Each message follows this structure consistently, regardless of the specific error. The "why" section is only included if the user can take direct action based on the reason. The "what to do next" section provides clear, concrete steps, avoiding vague instructions.

By treating repeated support questions as bugs in the error copy rather than documentation gaps, the author ensures that these issues are consistently addressed. This approach focuses attention on specific problematic messages and encourages continuous improvement through iterative refinement. Ultimately, this shift in perspective helps create error messages that guide users toward self-resolution, reducing support inquiries and preserving user trust.