first-run-copy

name	first-run-copy
description	Write and evaluate onboarding copy that helps a new user understand value, choose the next action, recover from uncertainty, and complete setup without unnecessary explanation or product jargon.

First-Run Copy

Use when onboarding screens, setup steps, empty states, permissions, imports, or first-use guidance need product copy.

Procedure

1. Identify the user's immediate goal, knowledge level, anxiety or uncertainty, and the action the interface needs them to take next.
2. Explain value before mechanics when the reason for a step is not self-evident.
3. Use the product's user language and concrete outcomes rather than internal feature names or implementation concepts.
4. Keep instructions close to the action they govern and remove text that duplicates obvious interface labels.
5. Clarify irreversible actions, permissions, data access, waiting states, and prerequisites before the user commits.
6. Write empty, error, skipped, and recovery states so onboarding does not become a dead end when the ideal path fails.
7. Check localization expansion, accessibility of instructions and errors, and whether copy still makes sense when read out of visual order.
8. Validate the copy in the real flow and hand broader voice or persuasive messaging decisions to the appropriate content specialist when needed.

Decision rules

• First-run copy should reduce uncertainty and move the user toward value.
• Do not explain every feature before the user needs it.
• Labels and instructions should name user concepts, not backend objects.
• Friendly tone cannot compensate for a confusing onboarding decision.

Quality gate

The copy is ready when a new user can understand why each non-obvious step matters, what to do next, what happens on failure or skip, and how to recover without relying on undocumented product knowledge.