288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
> **Additional context needed**: audience technical level and users' mental state in context.
|
|
|
|
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.
|
|
|
|
|
|
---
|
|
|
|
## Assess Current Copy
|
|
|
|
Identify what makes the text unclear or ineffective:
|
|
|
|
1. **Find clarity problems**:
|
|
- **Jargon**: Technical terms users won't understand
|
|
- **Ambiguity**: Multiple interpretations possible
|
|
- **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
|
|
- **Length**: Too wordy or too terse
|
|
- **Assumptions**: Assuming user knowledge they don't have
|
|
- **Missing context**: Users don't know what to do or why
|
|
- **Tone mismatch**: Too formal, too casual, or inappropriate for situation
|
|
|
|
2. **Understand the context**:
|
|
- Who's the audience? (Technical? General? First-time users?)
|
|
- What's the user's mental state? (Stressed during error? Confident during success?)
|
|
- What's the action? (What do we want users to do?)
|
|
- What's the constraint? (Character limits? Space limitations?)
|
|
|
|
**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
|
|
|
|
## Plan Copy Improvements
|
|
|
|
Create a strategy for clearer communication:
|
|
|
|
- **Primary message**: What's the ONE thing users need to know?
|
|
- **Action needed**: What should users do next (if anything)?
|
|
- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
|
|
- **Constraints**: Length limits, brand voice, localization considerations
|
|
|
|
**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
|
|
|
|
## Improve Copy Systematically
|
|
|
|
Refine text across these common areas:
|
|
|
|
### Error Messages
|
|
**Bad**: "Error 403: Forbidden"
|
|
**Good**: "You don't have permission to view this page. Contact your admin for access."
|
|
|
|
**Bad**: "Invalid input"
|
|
**Good**: "Email addresses need an @ symbol. Try: name@example.com"
|
|
|
|
**Principles**:
|
|
- Explain what went wrong in plain language
|
|
- Suggest how to fix it
|
|
- Don't blame the user
|
|
- Include examples when helpful
|
|
- Link to help/support if applicable
|
|
|
|
### Form Labels & Instructions
|
|
**Bad**: "DOB (MM/DD/YYYY)"
|
|
**Good**: "Date of birth" (with placeholder showing format)
|
|
|
|
**Bad**: "Enter value here"
|
|
**Good**: "Your email address" or "Company name"
|
|
|
|
**Principles**:
|
|
- Use clear, specific labels (not generic placeholders)
|
|
- Show format expectations with examples
|
|
- Explain why you're asking (when not obvious)
|
|
- Put instructions before the field, not after
|
|
- Keep required field indicators clear
|
|
|
|
### Button & CTA Text
|
|
**Bad**: "Click here" | "Submit" | "OK"
|
|
**Good**: "Create account" | "Save changes" | "Got it, thanks"
|
|
|
|
**Principles**:
|
|
- Describe the action specifically
|
|
- Use active voice (verb + noun)
|
|
- Match user's mental model
|
|
- Be specific ("Save" is better than "OK")
|
|
|
|
### Help Text & Tooltips
|
|
**Bad**: "This is the username field"
|
|
**Good**: "Choose a username. You can change this later in Settings."
|
|
|
|
**Principles**:
|
|
- Add value (don't just repeat the label)
|
|
- Answer the implicit question ("What is this?" or "Why do you need this?")
|
|
- Keep it brief but complete
|
|
- Link to detailed docs if needed
|
|
|
|
### Empty States
|
|
**Bad**: "No items"
|
|
**Good**: "No projects yet. Create your first project to get started."
|
|
|
|
**Principles**:
|
|
- Explain why it's empty (if not obvious)
|
|
- Show next action clearly
|
|
- Make it welcoming, not dead-end
|
|
|
|
### Success Messages
|
|
**Bad**: "Success"
|
|
**Good**: "Settings saved! Your changes will take effect immediately."
|
|
|
|
**Principles**:
|
|
- Confirm what happened
|
|
- Explain what happens next (if relevant)
|
|
- Be brief but complete
|
|
- Match the user's emotional moment (celebrate big wins)
|
|
|
|
### Loading States
|
|
**Bad**: "Loading..." (for 30+ seconds)
|
|
**Good**: "Analyzing your data... this usually takes 30-60 seconds"
|
|
|
|
**Principles**:
|
|
- Set expectations (how long?)
|
|
- Explain what's happening (when it's not obvious)
|
|
- Show progress when possible
|
|
- Offer escape hatch if appropriate ("Cancel")
|
|
|
|
### Confirmation Dialogs
|
|
**Bad**: "Are you sure?"
|
|
**Good**: "Delete 'Project Alpha'? This can't be undone."
|
|
|
|
**Principles**:
|
|
- State the specific action
|
|
- Explain consequences (especially for destructive actions)
|
|
- Use clear button labels ("Delete project" not "Yes")
|
|
- Don't overuse confirmations (only for risky actions)
|
|
|
|
### Navigation & Wayfinding
|
|
**Bad**: Generic labels like "Items" | "Things" | "Stuff"
|
|
**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
|
|
|
|
**Principles**:
|
|
- Be specific and descriptive
|
|
- Use language users understand (not internal jargon)
|
|
- Make hierarchy clear
|
|
- Consider information scent (breadcrumbs, current location)
|
|
|
|
## Apply Clarity Principles
|
|
|
|
Every piece of copy should follow these rules:
|
|
|
|
1. **Be specific**: "Enter email" not "Enter value"
|
|
2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
|
|
3. **Be active**: "Save changes" not "Changes will be saved"
|
|
4. **Be human**: "Oops, something went wrong" not "System error encountered"
|
|
5. **Tell users what to do**, not just what happened
|
|
6. **Be consistent**: Use same terms throughout (don't vary for variety)
|
|
|
|
**NEVER**:
|
|
- Use jargon without explanation
|
|
- Blame users ("You made an error" → "This field is required")
|
|
- Be vague ("Something went wrong" without explanation)
|
|
- Use passive voice unnecessarily
|
|
- Write overly long explanations (be concise)
|
|
- Use humor for errors (be empathetic instead)
|
|
- Assume technical knowledge
|
|
- Vary terminology (pick one term and stick with it)
|
|
- Repeat information (headers restating intros, redundant explanations)
|
|
- Use placeholders as the only labels (they disappear when users type)
|
|
|
|
## Verify Improvements
|
|
|
|
Test that copy improvements work:
|
|
|
|
- **Comprehension**: Can users understand without context?
|
|
- **Actionability**: Do users know what to do next?
|
|
- **Brevity**: Is it as short as possible while remaining clear?
|
|
- **Consistency**: Does it match terminology elsewhere?
|
|
- **Tone**: Is it appropriate for the situation?
|
|
|
|
When the copy reads cleanly, hand off to `$impeccable polish` for the final pass.
|
|
|
|
---
|
|
|
|
## Reference Material
|
|
|
|
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.
|
|
|
|
### 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.
|