89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
DRAFT: USER-FACING ERROR MESSAGE STYLE GUIDE
|
|
Version: 1.0-draft
|
|
Author: Quill (Draft lane)
|
|
Date: 2025-10-28
|
|
Status: Ready for review
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
This guide sets the minimum standard for all user-facing error text in products owned by the troupe. It covers:
|
|
- In-app error banners and toasts
|
|
- API error response bodies
|
|
- CLI stderr messages
|
|
- Email notifications about failures
|
|
|
|
It does not cover: log lines, internal monitoring alerts, or debug output.
|
|
|
|
## 2. Core Rules
|
|
|
|
Rule 1 — Say what happened, not what the system did.
|
|
Bad: "An error has occurred."
|
|
Good: "Your payment could not be processed."
|
|
|
|
Rule 2 — Say what the user can do next, or say nothing.
|
|
Bad: "An unexpected error occurred."
|
|
Good: "Retry in 2 minutes, or contact support@example.com."
|
|
If no action is reasonable, write: "Something went wrong on our side. We are investigating."
|
|
|
|
Rule 3 — One sentence per message unless the next sentence is a concrete action.
|
|
Max length: 140 characters for toasts/banners; 300 characters for email bodies.
|
|
|
|
Rule 4 — No jargon unless the audience is the technical user explicitly.
|
|
Bad: "NullPointerException in commit phase."
|
|
Good (for end user): "We could not save your changes."
|
|
Good (for technical user): "NullPointerException during commit phase (ID: abc123)."
|
|
|
|
Rule 5 — Tone: calm, direct, no exclamation marks.
|
|
Bad: "Oops! Something broke!"
|
|
Good: "Your upload failed."
|
|
|
|
## 3. Phrase Bank
|
|
|
|
Use these exact phrases where applicable:
|
|
- "Your [thing] could not be [action]."
|
|
- "We could not [action] your [thing]."
|
|
- "Try again. If it keeps failing, contact [support channel]."
|
|
- "Something went wrong on our side. We are investigating."
|
|
- "[Thing] is temporarily unavailable."
|
|
|
|
Avoid:
|
|
- "An error occurred"
|
|
- "Oops"
|
|
- "Sorry for the inconvenience"
|
|
- "Please try again later" (only if there is a known time bound)
|
|
|
|
## 4. Anti-patterns
|
|
|
|
1. Blaming the user without evidence.
|
|
Bad: "You entered an invalid file."
|
|
Good: "The file format is not supported."
|
|
|
|
2. Stack traces in user channels.
|
|
Never send raw tracebacks to end users.
|
|
|
|
3. Multiple errors in one message.
|
|
One root cause per message. Aggregate in a report if needed.
|
|
|
|
## 4. Checklist (ship-gate)
|
|
|
|
Every new or changed error message must pass:
|
|
- [ ] Says what happened in plain language.
|
|
- [ ] States one concrete action or says nothing.
|
|
- [ ] Is under the character limit for its surface.
|
|
- [ ] Has no jargon for the intended audience.
|
|
- [ ] Uses calm tone, no exclamation marks.
|
|
- [ ] Was read aloud once to catch awkward phrasing.
|
|
|
|
## 5. Measurement
|
|
|
|
Track weekly:
|
|
- % of user-facing error messages that include a concrete action.
|
|
- Mean character count per message surface (toast, email, API).
|
|
- Support ticket volume for the top 5 error messages.
|
|
|
|
## 6. Change log
|
|
|
|
- 1.0-draft (2025-10-28): Initial draft.
|