108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# UX Writing
|
|
|
|
## The Button Label Problem
|
|
|
|
**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
|
|
|
|
| Bad | Good | Why |
|
|
|-----|------|-----|
|
|
| OK | Save changes | Says what will happen |
|
|
| Submit | Create account | Outcome-focused |
|
|
| Yes | Delete message | Confirms the action |
|
|
| Cancel | Keep editing | Clarifies what "cancel" means |
|
|
| Click here | Download PDF | Describes the destination |
|
|
|
|
**For destructive actions**, name the destruction:
|
|
- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
|
|
- "Delete 5 items" not "Delete selected" (show the count)
|
|
|
|
## Error Messages: The Formula
|
|
|
|
Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
|
|
|
|
### Error Message Templates
|
|
|
|
| Situation | Template |
|
|
|-----------|----------|
|
|
| **Format error** | "[Field] needs to be [format]. Example: [example]" |
|
|
| **Missing required** | "Please enter [what's missing]" |
|
|
| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
|
|
| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
|
|
| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
|
|
|
|
### Don't Blame the User
|
|
|
|
Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
|
|
|
|
## Empty States Are Opportunities
|
|
|
|
Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
|
|
|
|
## Voice vs Tone
|
|
|
|
**Voice** is your brand's personality—consistent everywhere.
|
|
**Tone** adapts to the moment.
|
|
|
|
| Moment | Tone Shift |
|
|
|--------|------------|
|
|
| Success | Celebratory, brief: "Done! Your changes are live." |
|
|
| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
|
|
| Loading | Reassuring: "Saving your work..." |
|
|
| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
|
|
|
|
**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
|
|
|
|
## Writing for Accessibility
|
|
|
|
**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
|
|
|
|
## Writing for Translation
|
|
|
|
### Plan for Expansion
|
|
|
|
German text is ~30% longer than English. Allocate space:
|
|
|
|
| Language | Expansion |
|
|
|----------|-----------|
|
|
| German | +30% |
|
|
| French | +20% |
|
|
| Finnish | +30-40% |
|
|
| Chinese | -30% (fewer chars, but same width) |
|
|
|
|
### Translation-Friendly Patterns
|
|
|
|
Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
|
|
|
|
## Consistency: The Terminology Problem
|
|
|
|
Pick one term and stick with it:
|
|
|
|
| Inconsistent | Consistent |
|
|
|--------------|------------|
|
|
| Delete / Remove / Trash | Delete |
|
|
| Settings / Preferences / Options | Settings |
|
|
| Sign in / Log in / Enter | Sign in |
|
|
| Create / Add / New | Create |
|
|
|
|
Build a terminology glossary and enforce it. Variety creates confusion.
|
|
|
|
## Avoid Redundant Copy
|
|
|
|
If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
|
|
|
|
## Loading States
|
|
|
|
Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
|
|
|
|
## Confirmation Dialogs: Use Sparingly
|
|
|
|
Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
|
|
|
|
## Form Instructions
|
|
|
|
Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
|
|
|
|
---
|
|
|
|
**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.
|