Writing for product
Product copy helps users move fast. Every word should serve a purpose. See Voice and tone for the foundation.
General principles
- Be direct. Tell users what to do, not what they can do.
- Be specific. Name the exact thing being affected.
- Be brief. Users scan interfaces, they don’t read them.
Buttons and CTAs
Buttons should use action verbs that describe exactly what will happen. Avoid generic labels.
✅ Do:
- Create service
- Delete query
- Export as CSV
- Save changes
❌ Don’t:
- OK
- Confirm
- Submit
- Yes
For destructive actions, be explicit about what’s being destroyed:
✅ Do: Delete “my-analytics-service”
❌ Don’t: Delete service
Form labels and placeholders
Labels should clearly identify what information is needed. Placeholders should show format or provide an example—never use them as labels.
✅ Do:
- Label: “Email address”
- Placeholder: “you@company.com”
❌ Don’t:
- Label: (none)
- Placeholder: “Email address” (using placeholder as label)
Mark required fields clearly. Don’t make users guess.
Error messages
Errors should tell users what happened and what to do. Be direct. Never blame the user. Skip the cutesy “oops.”
Structure
- What happened (briefly)
- What to do next (if actionable)
✅ Do: Connection timed out. Check your network settings and try again.
❌ Don’t: Error: ETIMEDOUT
❌ Don’t: You entered an invalid value.
What to avoid in errors
- Blame: “You entered…” → “The value…”
- Cutesy language: “Oops!” “Uh oh!” “Whoops!”
- Vague apologies: “Something went wrong.”
- Raw error codes: Show them, but explain them
✅ Do: Invalid API key. Generate a new key in Settings → API Keys.
❌ Don’t: Oops! We couldn’t authenticate your request. Please try again later.
Empty states
Empty states are opportunities to guide users. Tell them why it’s empty and what action to take.
✅ Do: No queries yet. Run your first query to see results here.
❌ Don’t: No data.
Tooltips and hints
Keep tooltips short—one sentence when possible. They should add context, not repeat what’s already visible.
✅ Do: Tooltip for “Memory limit”: Maximum memory this query can use before being terminated.
❌ Don’t: Tooltip for “Memory limit”: This is the memory limit setting.
Confirmation dialogs
Confirmation dialogs prevent users from making irreversible or dangerous actions. For detailed guidance, see the Confirmation dialogs page.
Quick tips
- Title: Phrase as a question including the action and target
- Actions: Use specific verbs, not “OK” or “Confirm”
- Description: Explain consequences briefly (1-2 sentences)
✅ Do:
- Title: Delete “production-db”?
- Description: This will permanently delete the service and all its data.
- Actions: Cancel / Delete service
❌ Don’t:
- Title: Are you sure?
- Description: This action cannot be undone.
- Actions: Cancel / OK
Loading and progress states
Tell users what’s happening during longer operations.
✅ Do:
- Creating service…
- Importing 1,234 rows…
- Connecting to database…
❌ Don’t:
- Loading…
- Please wait…
- Processing…
Success messages
Confirm what happened. Be specific but brief.
✅ Do:
- Service created successfully
- Query saved to “My Queries”
- API key copied to clipboard
❌ Don’t:
- Success!
- Done.
- Operation completed successfully.
Formatting in UI
Use bold for UI element names when writing instructions:
✅ Do: Click the Start button.
❌ Don’t: Click the Start button.