Writing user-facing copy
This is the operational gate for anything a person reads in the product or around it.
Run it before writing or editing user-facing text, and whenever a code change introduces or changes a visible string.
Applies to: UI labels, buttons, form fields, tooltips, empty states, error and success messages, toasts and notifications, onboarding flows, emails, docs, and support replies.
Does not apply to: code comments, commit messages, log lines, variable/function names, or other developer-only text.
Voice
Write the way a person would. Neutral and humane.
- Sentence case. Capitalize only the first word and proper nouns. "Save as view", not "Save As View". "Product analytics", not "Product Analytics".
- Be direct and friendly. Say what happened and what to do next.
- Plain language, no jargon. Use the label the user sees, not the internal name.
surveyPopupDelaySeconds becomes "Delay the survey popup".
- Don't editorialize. State what is, not how exciting it is. Cut "powerful", "seamless", "effortless", "simply", "just", "easily", "supercharge", "unlock".
- No sales-y or edgy copy. No marketing hooks, no clever one-liners, no hype.
- American English spelling. "color", "analyze", "canceled".
Specific rules
No em-dashes
Do not use em-dashes (—) anywhere in user-facing copy.
Do not substitute an en-dash either.
Prefer rewriting the sentence so the dash isn't needed. If a connector is unavoidable, use a hyphen with spaces, a comma, a colon, or split into two sentences.
- ❌ "Save this view — you can reuse it later."
- ✅ "Save this view. You can reuse it later."
- ✅ "Save this view to reuse it later."
Also avoid the sentence shapes that lean on that dash, because they read as machine-written:
- ❌ "This isn't just a filter, it's a saved view." (the "not just X, but Y" construction)
- ❌ "It's fast, it's simple, it's yours." (rule-of-three padding)
- ❌ Hedging preambles like "It's worth noting that…", "Keep in mind that…".
Write the plain version instead.
No punchy or clever phrasing
This is the failure mode that slips through even when you know the rule, so check for it specifically. It applies to every string, including headings, section titles, and button labels, not just body text.
The tells:
- Antithesis ("X, not Y" / "X, they don't Y") used for effect. ❌ "Errors guide, they don't dead-end." → ✅ "Errors point to a next step."
- A heading written to sound weighty. ❌ "The rules that are easy to break" → ✅ "Common mistakes".
- A clever or dramatic closing line. ❌ "Never leave the user staring at a failure." → ✅ "Say what happened and what to do next."
- Filler that sounds like a principle but adds nothing. ❌ "This is a tool people use to get work done." → cut it.
- Emphasis the sentence doesn't need. ❌ "This will completely transform how you work." → ✅ "This changes how X works."
After drafting, re-read and cut anything that's there to sound good rather than to inform. If a line would feel out of place said plainly out loud to a colleague, rewrite it.
Errors and empty states point to a next step
Say what happened and give the next action. Don't stop at reporting that something failed.
- ❌ "Something went wrong."
- ✅ "Couldn't load your insights. Refresh the page, and if it keeps happening contact support."
How to talk about features
Use the names users see, and stay consistent across every surface.
Wizard
The setup tool is named Wizard. It confuses users as a description, because "wizard" reads like an old-style step-by-step form, not an AI. Users already have a mental model for AI agents.
- Use "Wizard" only as the feature's proper name (the thing you're pointing at).
- To explain what it does, always call it "the setup agent" or "the agent".
Examples:
- ✅ "Wizard sets up PostHog for you. The setup agent installs the SDK and wires up your first events."
- ✅ "Ask the agent to add error tracking."
- ❌ "Use the wizard to walk through setup." (using "wizard" as a description)
- ❌ "The wizard will guide you through each step." (reinforces the wrong mental model)
For any other feature, use its product-facing name exactly as it appears in the UI, and describe it in the terms users already understand.
When unsure
If you can't tell whether copy reads well, or whether a term is the right user-facing name, ask a human before shipping it.
1---
2name: writing-user-facing-copy
3description: >
4 Sets the voice and word choices for any text a person reads in PostHog: UI labels, buttons, tooltips, empty and error states, notifications, in-app messages, onboarding, docs, and support replies.
5 Use ALWAYS before writing or editing user-facing copy, and whenever a code change adds or changes a string a user will see.
6 Enforces a humane, neutral tone: no editorializing, no sales-y or edgy one-liners, no em-dashes (use hyphens or rewrite), sentence case, plain language.
7 Also carries feature-naming rules that are easy to get wrong, most importantly how to talk about the Wizard (name it "Wizard" once, then call it "the setup agent" / "the agent").
8 Not for internal code comments, commit messages, or variable names.
9---
10
11# Writing user-facing copy
12
13This is the operational gate for anything a person reads in the product or around it.
14Run it before writing or editing user-facing text, and whenever a code change introduces or changes a visible string.
15
16Applies to: UI labels, buttons, form fields, tooltips, empty states, error and success messages, toasts and notifications, onboarding flows, emails, docs, and support replies.
17Does not apply to: code comments, commit messages, log lines, variable/function names, or other developer-only text.
18
19## Voice
20
21Write the way a person would. Neutral and humane.
22
23- **Sentence case.** Capitalize only the first word and proper nouns. "Save as view", not "Save As View". "Product analytics", not "Product Analytics".
24- **Be direct and friendly.** Say what happened and what to do next.
25- **Plain language, no jargon.** Use the label the user sees, not the internal name. `surveyPopupDelaySeconds` becomes "Delay the survey popup".
26- **Don't editorialize.** State what is, not how exciting it is. Cut "powerful", "seamless", "effortless", "simply", "just", "easily", "supercharge", "unlock".
27- **No sales-y or edgy copy.** No marketing hooks, no clever one-liners, no hype.
28- **American English spelling.** "color", "analyze", "canceled".
29
30## Specific rules
31
32### No em-dashes
33
34Do not use em-dashes (—) anywhere in user-facing copy.
35Do not substitute an en-dash either.
36
37Prefer rewriting the sentence so the dash isn't needed. If a connector is unavoidable, use a hyphen with spaces, a comma, a colon, or split into two sentences.
38
39- ❌ "Save this view — you can reuse it later."
40- ✅ "Save this view. You can reuse it later."
41- ✅ "Save this view to reuse it later."
42
43Also avoid the sentence _shapes_ that lean on that dash, because they read as machine-written:
44
45- ❌ "This isn't just a filter, it's a saved view." (the "not just X, but Y" construction)
46- ❌ "It's fast, it's simple, it's yours." (rule-of-three padding)
47- ❌ Hedging preambles like "It's worth noting that…", "Keep in mind that…".
48
49Write the plain version instead.
50
51### No punchy or clever phrasing
52
53This is the failure mode that slips through even when you know the rule, so check for it specifically. It applies to every string, including headings, section titles, and button labels, not just body text.
54
55The tells:
56
57- **Antithesis** ("X, not Y" / "X, they don't Y") used for effect. ❌ "Errors guide, they don't dead-end." → ✅ "Errors point to a next step."
58- **A heading written to sound weighty.** ❌ "The rules that are easy to break" → ✅ "Common mistakes".
59- **A clever or dramatic closing line.** ❌ "Never leave the user staring at a failure." → ✅ "Say what happened and what to do next."
60- **Filler that sounds like a principle but adds nothing.** ❌ "This is a tool people use to get work done." → cut it.
61- **Emphasis the sentence doesn't need.** ❌ "This will completely transform how you work." → ✅ "This changes how X works."
62
63After drafting, re-read and cut anything that's there to sound good rather than to inform. If a line would feel out of place said plainly out loud to a colleague, rewrite it.
64
65### Errors and empty states point to a next step
66
67Say what happened and give the next action. Don't stop at reporting that something failed.
68
69- ❌ "Something went wrong."
70- ✅ "Couldn't load your insights. Refresh the page, and if it keeps happening contact support."
71
72## How to talk about features
73
74Use the names users see, and stay consistent across every surface.
75
76### Wizard
77
78The setup tool is named **Wizard**. It confuses users as a description, because "wizard" reads like an old-style step-by-step form, not an AI. Users already have a mental model for AI agents.
79
80- Use "Wizard" **only** as the feature's proper name (the thing you're pointing at).
81- To explain what it does, always call it **"the setup agent"** or **"the agent"**.
82
83Examples:
84
85- ✅ "Wizard sets up PostHog for you. The setup agent installs the SDK and wires up your first events."
86- ✅ "Ask the agent to add error tracking."
87- ❌ "Use the wizard to walk through setup." (using "wizard" as a description)
88- ❌ "The wizard will guide you through each step." (reinforces the wrong mental model)
89
90For any other feature, use its product-facing name exactly as it appears in the UI, and describe it in the terms users already understand.
91
92## When unsure
93
94If you can't tell whether copy reads well, or whether a term is the right user-facing name, ask a human before shipping it.
posthog