| 1 | > **Additional context needed**: audience technical level and users' mental state in context. |
| 2 | |
| 3 | Find the unclear, confusing, or poorly written interface text and rewrite it. Vague copy creates support tickets and abandonment; specific copy gets users through the task. |
| 4 | |
| 5 | |
| 6 | --- |
| 7 | |
| 8 | ## Assess Current Copy |
| 9 | |
| 10 | Identify what makes the text unclear or ineffective: |
| 11 | |
| 12 | 1. **Find clarity problems**: |
| 13 | - **Jargon**: Technical terms users won't understand |
| 14 | - **Ambiguity**: Multiple interpretations possible |
| 15 | - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file" |
| 16 | - **Length**: Too wordy or too terse |
| 17 | - **Assumptions**: Assuming user knowledge they don't have |
| 18 | - **Missing context**: Users don't know what to do or why |
| 19 | - **Tone mismatch**: Too formal, too casual, or inappropriate for situation |
| 20 | |
| 21 | 2. **Understand the context**: |
| 22 | - Who's the audience? (Technical? General? First-time users?) |
| 23 | - What's the user's mental state? (Stressed during error? Confident during success?) |
| 24 | - What's the action? (What do we want users to do?) |
| 25 | - What's the constraint? (Character limits? Space limitations?) |
| 26 | |
| 27 | **CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets. |
| 28 | |
| 29 | ## Plan Copy Improvements |
| 30 | |
| 31 | Create a strategy for clearer communication: |
| 32 | |
| 33 | - **Primary message**: What's the ONE thing users need to know? |
| 34 | - **Action needed**: What should users do next (if anything)? |
| 35 | - **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?) |
| 36 | - **Constraints**: Length limits, brand voice, localization considerations |
| 37 | |
| 38 | **IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words. |
| 39 | |
| 40 | ## Improve Copy Systematically |
| 41 | |
| 42 | Refine text across these common areas: |
| 43 | |
| 44 | ### Error Messages |
| 45 | **Bad**: "Error 403: Forbidden" |
| 46 | **Good**: "You don't have permission to view this page. Contact your admin for access." |
| 47 | |
| 48 | **Bad**: "Invalid input" |
| 49 | **Good**: "Email addresses need an @ symbol. Try: name@example.com" |
| 50 | |
| 51 | **Principles**: |
| 52 | - Explain what went wrong in plain language |
| 53 | - Suggest how to fix it |
| 54 | - Don't blame the user |
| 55 | - Include examples when helpful |
| 56 | - Link to help/support if applicable |
| 57 | |
| 58 | ### Form Labels & Instructions |
| 59 | **Bad**: "DOB (MM/DD/YYYY)" |
| 60 | **Good**: "Date of birth" (with placeholder showing format) |
| 61 | |
| 62 | **Bad**: "Enter value here" |
| 63 | **Good**: "Your email address" or "Company name" |
| 64 | |
| 65 | **Principles**: |
| 66 | - Use clear, specific labels (not generic placeholders) |
| 67 | - Show format expectations with examples |
| 68 | - Explain why you're asking (when not obvious) |
| 69 | - Put instructions before the field, not after |
| 70 | - Keep required field indicators clear |
| 71 | |
| 72 | ### Button & CTA Text |
| 73 | **Bad**: "Click here" | "Submit" | "OK" |
| 74 | **Good**: "Create account" | "Save changes" | "Got it, thanks" |
| 75 | |
| 76 | **Principles**: |
| 77 | - Describe the action specifically |
| 78 | - Use active voice (verb + noun) |
| 79 | - Match user's mental model |
| 80 | - Be specific ("Save" is better than "OK") |
| 81 | |
| 82 | ### Help Text & Tooltips |
| 83 | **Bad**: "This is the username field" |
| 84 | **Good**: "Choose a username. You can change this later in Settings." |
| 85 | |
| 86 | **Principles**: |
| 87 | - Add value (don't just repeat the label) |
| 88 | - Answer the implicit question ("What is this?" or "Why do you need this?") |
| 89 | - Keep it brief but complete |
| 90 | - Link to detailed docs if needed |
| 91 | |
| 92 | ### Empty States |
| 93 | **Bad**: "No items" |
| 94 | **Good**: "No projects yet. Create your first project to get started." |
| 95 | |
| 96 | **Principles**: |
| 97 | - Explain why it's empty (if not obvious) |
| 98 | - Show next action clearly |
| 99 | - Make it welcoming, not dead-end |
| 100 | |
| 101 | ### Success Messages |
| 102 | **Bad**: "Success" |
| 103 | **Good**: "Settings saved! Your changes will take effect immediately." |
| 104 | |
| 105 | **Principles**: |
| 106 | - Confirm what happened |
| 107 | - Explain what happens next (if relevant) |
| 108 | - Be brief but complete |
| 109 | - Match the user's emotional moment (celebrate big wins) |
| 110 | |
| 111 | ### Loading States |
| 112 | **Bad**: "Loading..." (for 30+ seconds) |
| 113 | **Good**: "Analyzing your data... this usually takes 30-60 seconds" |
| 114 | |
| 115 | **Principles**: |
| 116 | - Set expectations (how long?) |
| 117 | - Explain what's happening (when it's not obvious) |
| 118 | - Show progress when possible |
| 119 | - Offer escape hatch if appropriate ("Cancel") |
| 120 | |
| 121 | ### Confirmation Dialogs |
| 122 | **Bad**: "Are you sure?" |
| 123 | **Good**: "Delete 'Project Alpha'? This can't be undone." |
| 124 | |
| 125 | **Principles**: |
| 126 | - State the specific action |
| 127 | - Explain consequences (especially for destructive actions) |
| 128 | - Use clear button labels ("Delete project" not "Yes") |
| 129 | - Don't overuse confirmations (only for risky actions) |
| 130 | |
| 131 | ### Navigation & Wayfinding |
| 132 | **Bad**: Generic labels like "Items" | "Things" | "Stuff" |
| 133 | **Good**: Specific labels like "Your projects" | "Team members" | "Settings" |
| 134 | |
| 135 | **Principles**: |
| 136 | - Be specific and descriptive |
| 137 | - Use language users understand (not internal jargon) |
| 138 | - Make hierarchy clear |
| 139 | - Consider information scent (breadcrumbs, current location) |
| 140 | |
| 141 | ## Apply Clarity Principles |
| 142 | |
| 143 | Every piece of copy should follow these rules: |
| 144 | |
| 145 | 1. **Be specific**: "Enter email" not "Enter value" |
| 146 | 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity) |
| 147 | 3. **Be active**: "Save changes" not "Changes will be saved" |
| 148 | 4. **Be human**: "Oops, something went wrong" not "System error encountered" |
| 149 | 5. **Tell users what to do**, not just what happened |
| 150 | 6. **Be consistent**: Use same terms throughout (don't vary for variety) |
| 151 | |
| 152 | **NEVER**: |
| 153 | - Use jargon without explanation |
| 154 | - Blame users ("You made an error" → "This field is required") |
| 155 | - Be vague ("Something went wrong" without explanation) |
| 156 | - Use passive voice unnecessarily |
| 157 | - Write overly long explanations (be concise) |
| 158 | - Use humor for errors (be empathetic instead) |
| 159 | - Assume technical knowledge |
| 160 | - Vary terminology (pick one term and stick with it) |
| 161 | - Repeat information (headers restating intros, redundant explanations) |
| 162 | - Use placeholders as the only labels (they disappear when users type) |
| 163 | |
| 164 | ## Verify Improvements |
| 165 | |
| 166 | Test that copy improvements work: |
| 167 | |
| 168 | - **Comprehension**: Can users understand without context? |
| 169 | - **Actionability**: Do users know what to do next? |
| 170 | - **Brevity**: Is it as short as possible while remaining clear? |
| 171 | - **Consistency**: Does it match terminology elsewhere? |
| 172 | - **Tone**: Is it appropriate for the situation? |
| 173 | |
| 174 | When the copy reads cleanly, hand off to `$impeccable polish` for the final pass. |
| 175 | |
| 176 | --- |
| 177 | |
| 178 | ## Reference Material |
| 179 | |
| 180 | The sections below were previously `ux-writing.md` and live inline now so the clarify flow has its deep UX-writing reference in one place. |
| 181 | |
| 182 | ### UX Writing |
| 183 | |
| 184 | #### The Button Label Problem |
| 185 | |
| 186 | **Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns: |
| 187 | |
| 188 | | Bad | Good | Why | |
| 189 | |-----|------|-----| |
| 190 | | OK | Save changes | Says what will happen | |
| 191 | | Submit | Create account | Outcome-focused | |
| 192 | | Yes | Delete message | Confirms the action | |
| 193 | | Cancel | Keep editing | Clarifies what "cancel" means | |
| 194 | | Click here | Download PDF | Describes the destination | |
| 195 | |
| 196 | **For destructive actions**, name the destruction: |
| 197 | - "Delete" not "Remove" (delete is permanent, remove implies recoverable) |
| 198 | - "Delete 5 items" not "Delete selected" (show the count) |
| 199 | |
| 200 | #### Error Messages: The Formula |
| 201 | |
| 202 | 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". |
| 203 | |
| 204 | ##### Error Message Templates |
| 205 | |
| 206 | | Situation | Template | |
| 207 | |-----------|----------| |
| 208 | | **Format error** | "[Field] needs to be [format]. Example: [example]" | |
| 209 | | **Missing required** | "Please enter [what's missing]" | |
| 210 | | **Permission denied** | "You don't have access to [thing]. [What to do instead]" | |
| 211 | | **Network error** | "We couldn't reach [thing]. Check your connection and [action]." | |
| 212 | | **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" | |
| 213 | |
| 214 | ##### Don't Blame the User |
| 215 | |
| 216 | Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date". |
| 217 | |
| 218 | #### Empty States Are Opportunities |
| 219 | |
| 220 | 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". |
| 221 | |
| 222 | #### Voice vs Tone |
| 223 | |
| 224 | **Voice** is your brand's personality, consistent everywhere. |
| 225 | **Tone** adapts to the moment. |
| 226 | |
| 227 | | Moment | Tone Shift | |
| 228 | |--------|------------| |
| 229 | | Success | Celebratory, brief: "Done! Your changes are live." | |
| 230 | | Error | Empathetic, helpful: "That didn't work. Here's what to try..." | |
| 231 | | Loading | Reassuring: "Saving your work..." | |
| 232 | | Destructive confirm | Serious, clear: "Delete this project? This can't be undone." | |
| 233 | |
| 234 | **Never use humor for errors.** Users are already frustrated. Be helpful, not cute. |
| 235 | |
| 236 | #### Writing for Accessibility |
| 237 | |
| 238 | **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. |
| 239 | |
| 240 | #### Writing for Translation |
| 241 | |
| 242 | ##### Plan for Expansion |
| 243 | |
| 244 | German text is ~30% longer than English. Allocate space: |
| 245 | |
| 246 | | Language | Expansion | |
| 247 | |----------|-----------| |
| 248 | | German | +30% | |
| 249 | | French | +20% | |
| 250 | | Finnish | +30-40% | |
| 251 | | Chinese | -30% (fewer chars, but same width) | |
| 252 | |
| 253 | ##### Translation-Friendly Patterns |
| 254 | |
| 255 | 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. |
| 256 | |
| 257 | #### Consistency: The Terminology Problem |
| 258 | |
| 259 | Pick one term and stick with it: |
| 260 | |
| 261 | | Inconsistent | Consistent | |
| 262 | |--------------|------------| |
| 263 | | Delete / Remove / Trash | Delete | |
| 264 | | Settings / Preferences / Options | Settings | |
| 265 | | Sign in / Log in / Enter | Sign in | |
| 266 | | Create / Add / New | Create | |
| 267 | |
| 268 | Build a terminology glossary and enforce it. Variety creates confusion. |
| 269 | |
| 270 | #### Avoid Redundant Copy |
| 271 | |
| 272 | 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. |
| 273 | |
| 274 | #### Loading States |
| 275 | |
| 276 | Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress. |
| 277 | |
| 278 | #### Confirmation Dialogs: Use Sparingly |
| 279 | |
| 280 | 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"). |
| 281 | |
| 282 | #### Form Instructions |
| 283 | |
| 284 | Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking. |
| 285 | |
| 286 | --- |
| 287 | |
| 288 | **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. |
| 289 |