Rewrote error messages to stop blaming users
Rewrote the application's error messages against a written tone
standard after a refused sign‑in blamed the user for mistyping when
the provider actually required an app‑specific password, and covered
it with a test that names the provider.
September 2026

Situation. A sign‑in against a major mail provider failed, and the
application told the user their password was incorrect. It was not
incorrect. That provider requires an application‑specific password
for third‑party clients and rejects the account password regardless
of how carefully it is typed. The message sent the user to retype
something that could never work, and the actual instruction — go and
generate a different kind of password — appeared nowhere.

Task. The error messages had to be rewritten against a written
standard rather than patched one at a time, since this one was the
visible instance of a habit running through all of them.

Action. The standard has three requirements: say what happened,
never imply the user did something wrong when the cause is
elsewhere, and give the next action when one exists. Applied across
the error surface, most messages violated at least one — several
were the underlying library's error string passed through, which
describes a condition to a programmer rather than a situation to a
person. The provider case was rewritten to name the provider, state
that it requires an app‑specific password for other clients, and say
where to create one. The test is what stops it regressing, and it is
deliberately specific: it drives a sign‑in failure against that
provider and asserts the message contains the provider's name and
the phrase describing the required credential type. A test asserting
only that some error appeared would pass on the original wrong
message, so the assertion is on the content, which is the only part
that was ever broken.

Result. The error surface follows a stated standard and the case
that prompted it is covered by a test that fails on the old text.
What remains unresolved is scale: the standard is enforced by review
and by one test on one message, and the other providers with their
own particular requirements have no equivalent test, so the class is
documented rather than closed.

Categories:
1Frontend Engineering	/categories/frontend/	software.engineer.company	70
1Security	/categories/security/	software.engineer.company	70
1Testing & QA	/categories/testing/	software.engineer.company	70
1UX / UI Design	/categories/ux-ui/	software.engineer.company	70
1Product & Requirements	/categories/product/	software.engineer.company	70
1Documentation	/categories/documentation/	software.engineer.company	70

Services:
1UI/UX Design & Design Systems	/services/ui-ux-design/	software.engineer.company	70
1Product Strategy & Requirements	/services/product-strategy/	software.engineer.company	70
1Technical Documentation	/services/technical-documentation/	software.engineer.company	70

hThis page on the web	URL:https://software.engineer.company/portfolio/rewrote-error-messages-to-stop-blaming-users/	software.engineer.company	70
