| 1 | # UX Writing |
| 2 | |
| 3 | ## The Button Label Problem |
| 4 | |
| 5 | **Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns: |
| 6 | |
| 7 | | Bad | Good | Why | |
| 8 | |-----|------|-----| |
| 9 | | OK | Save changes | Says what will happen | |
| 10 | | Submit | Create account | Outcome-focused | |
| 11 | | Yes | Delete message | Confirms the action | |
| 12 | | Cancel | Keep editing | Clarifies what "cancel" means | |
| 13 | | Click here | Download PDF | Describes the destination | |
| 14 | |
| 15 | **For destructive actions**, name the destruction: |
| 16 | - "Delete" not "Remove" (delete is permanent, remove implies recoverable) |
| 17 | - "Delete 5 items" not "Delete selected" (show the count) |
| 18 | |
| 19 | ## Error Messages: The Formula |
| 20 | |
| 21 | 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". |
| 22 | |
| 23 | ### Error Message Templates |
| 24 | |
| 25 | | Situation | Template | |
| 26 | |-----------|----------| |
| 27 | | **Format error** | "[Field] needs to be [format]. Example: [example]" | |
| 28 | | **Missing required** | "Please enter [what's missing]" | |
| 29 | | **Permission denied** | "You don't have access to [thing]. [What to do instead]" | |
| 30 | | **Network error** | "We couldn't reach [thing]. Check your connection and [action]." | |
| 31 | | **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" | |
| 32 | |
| 33 | ### Don't Blame the User |
| 34 | |
| 35 | Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date". |
| 36 | |
| 37 | ## Empty States Are Opportunities |
| 38 | |
| 39 | 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". |
| 40 | |
| 41 | ## Voice vs Tone |
| 42 | |
| 43 | **Voice** is your brand's personality, consistent everywhere. |
| 44 | **Tone** adapts to the moment. |
| 45 | |
| 46 | | Moment | Tone Shift | |
| 47 | |--------|------------| |
| 48 | | Success | Celebratory, brief: "Done! Your changes are live." | |
| 49 | | Error | Empathetic, helpful: "That didn't work. Here's what to try..." | |
| 50 | | Loading | Reassuring: "Saving your work..." | |
| 51 | | Destructive confirm | Serious, clear: "Delete this project? This can't be undone." | |
| 52 | |
| 53 | **Never use humor for errors.** Users are already frustrated. Be helpful, not cute. |
| 54 | |
| 55 | ## Writing for Accessibility |
| 56 | |
| 57 | **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. |
| 58 | |
| 59 | ## Writing for Translation |
| 60 | |
| 61 | ### Plan for Expansion |
| 62 | |
| 63 | German text is ~30% longer than English. Allocate space: |
| 64 | |
| 65 | | Language | Expansion | |
| 66 | |----------|-----------| |
| 67 | | German | +30% | |
| 68 | | French | +20% | |
| 69 | | Finnish | +30-40% | |
| 70 | | Chinese | -30% (fewer chars, but same width) | |
| 71 | |
| 72 | ### Translation-Friendly Patterns |
| 73 | |
| 74 | 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. |
| 75 | |
| 76 | ## Consistency: The Terminology Problem |
| 77 | |
| 78 | Pick one term and stick with it: |
| 79 | |
| 80 | | Inconsistent | Consistent | |
| 81 | |--------------|------------| |
| 82 | | Delete / Remove / Trash | Delete | |
| 83 | | Settings / Preferences / Options | Settings | |
| 84 | | Sign in / Log in / Enter | Sign in | |
| 85 | | Create / Add / New | Create | |
| 86 | |
| 87 | Build a terminology glossary and enforce it. Variety creates confusion. |
| 88 | |
| 89 | ## Avoid Redundant Copy |
| 90 | |
| 91 | 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. |
| 92 | |
| 93 | ## Loading States |
| 94 | |
| 95 | Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress. |
| 96 | |
| 97 | ## Confirmation Dialogs: Use Sparingly |
| 98 | |
| 99 | 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"). |
| 100 | |
| 101 | ## Form Instructions |
| 102 | |
| 103 | Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking. |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | **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. |
| 108 |