zmjafary PostHog voice
Unofficial. Not affiliated with, endorsed by, or sponsored by PostHog. It restates style rules PostHog publishes openly in its handbook.
PostHog publishes its style rules openly. This skill encodes them so what you write matches that style, or borrows the best parts of it.
The one sentence that generates everything else
Write the way you'd explain something to a smart friend, not a business associate you're trying to impress or a prospect you're trying to close.
– PostHog handbook, Voice and tone
If a sentence would embarrass you to say out loud to a competent engineer sitting next to you, cut it. Every rule below is downstream of this.
Step 1: Pick the register, then load its reference file
Voice is constant. Humor, length, and formality flex by surface. Read the matching file before drafting.
| The user wants | Read |
|---|---|
| Blog post, newsletter, opinion piece, engineering deep-dive, comparison post, launch announcement | references/blog.md |
| Docs page, tutorial, integration guide, API reference, troubleshooting | references/docs.md |
| Handbook page, landing page, pricing copy, UI microcopy, changelog, social post, press | references/product.md |
| Rewriting or reviewing someone else's copy | references/rewrites.md |
| Any specific punctuation, spelling, or word-choice question | references/mechanics.md |
If it is ambiguous, ask once, then default to blog.
Step 2: Voice rules that apply to everything
Be opinionated. Content must make an argument. It is better to be slightly wrong or controversial than to say nothing. Never sit on the fence, never conclude "it depends," never write "there are pros and cons to both." Pick the side you actually believe and defend it. PostHog's most-read posts are the ones with a thesis in the title.
Be specific. Concrete nouns, real numbers, named tools, actual code. "We cut p99 latency from 2s to 94ms" beats "we significantly improved performance." If you cannot produce a number, produce an example. If you cannot produce an example, the claim is probably empty and should be cut.
Be honest, including about yourself. Say what the product does not do. Name the limitations. Publish the mistake. Steelman competitors, never straw-man them, on the assumption that the competitor is reading and will happily dunk on you for being dishonest. This is a trust mechanism, not a risk.
Get to the point. Lead with the answer, then expand. Almost every draft improves by shortening or deleting the intro. Never open with a mission statement, a definition of the industry, or "In today's fast-paced world." Never write a second intro after the first one.
Address the reader as "you." Say "this helps you ship faster," not "this helps organizations accelerate delivery." The reader's product is the subject; the tool is the means, never the hero.
Use contractions. Start sentences with "But" and "And" when it reads better. Write in active voice.
Be funny only when you're actually funny. If the joke needs a footnote, it has already failed. Humor that works is specific, unexpected, and comes from a real point of view. Humor that fails is a wacky metaphor bolted onto a SaaS feature. Clear beats clever. Put jokes in intros, asides, callouts, alt text, and social, never in the middle of an instruction.
Never sound like a generic software company. That is the actual failure mode. Forgettable kills faster than a bad joke.
Step 3: Mechanics that are non-negotiable
These are objective and get checked every time. Full detail and edge cases in references/mechanics.md.
- American English spelling, dates, and grammar.
- Spaced en dash ( – ), never an em dash. PostHog's editor checks this one by hand. Never substitute a bare hyphen for a dash.
- Sentence case for every heading and title. "Documentation style guide," not "Documentation Style Guide."
- Feature names lowercase: feature flags, session replay, product analytics, error tracking. They are common nouns. Capitalize only in a formal product-name context.
- Oxford comma, always.
- Straight quotes and apostrophes, never curly.
- "enable," not "allow." Allow implies permission. Enable means providing the means.
- No emojis in body copy. They read as try-hard.
- Short paragraphs. A paragraph should not run more lines than you have fingers on one hand. Docs cap at three or four lines.
- Grade 8 readability or lower.
- List lengths of 2, 3, 5, or 7. Four and six feel awkward.
- snake_case for event and property names in examples.
- open source as a noun, open-source before a noun.
- allowlist / denylist, never whitelist / blacklist.
- Acronyms capitalized (URLs, not urls), defined or linked on first use.
Step 4: Delete these words on sight
Every one of these is a hedge, a buzzword, or a claim pretending to be evidence. Replace, don't soften.
| Never write | Write instead |
|---|---|
| leverage | use |
| utilize | use |
| empowers teams to | say what teams can now do |
| enables you to unlock | say what they get |
| helps you to | say what it does |
| streamline | speed up, simplify |
| robust | strong, solid, or describe it |
| seamless | describe why it's easy |
| best-in-class | show a number instead |
| holistic | comprehensive, or name the parts |
| synergy | (nothing, delete) |
| revolutionary, game-changing, supercharge | describe the actual change |
| unlock actionable insights | say what the user learns |
| all-in-one platform for modern teams | say who it's for and what it does |
| Introducing our new [feature] | lead with what the reader can now do |
| It depends / it's complicated | pick a side |
The longer kill-list, plus preferred PostHog vocabulary ("ship," "self-serve," "product engineer," "opinionated," "steelman"), lives in references/mechanics.md.
Step 5: Draft, then run the lint
After drafting, check the mechanics deterministically instead of by eye:
python3 ~/.claude/skills/posthog-voice/scripts/lint.py path/to/draft.md
The path is absolute because your working directory is the user's project, not the skill's. If the skill is installed somewhere else, use that path instead.
It flags em dashes, curly quotes, emojis, title-case headings, banned words, capitalized feature names, overlong paragraphs, and passive-voice tells.
Fix every DASH, QUOTE, EMOJI, CASE, WORD, PHRASE, FEATURE, ALLOW, and FENCE hit. PASSIVE, PARA, and LENGTH are advisory heuristics: read them, then decide. Do not rewrite correct prose to satisfy them. The linter catches mechanics; it cannot tell you whether the piece makes an argument.
Step 6: Ship checklist
Do not deliver until every answer is yes.
- Does it make an argument someone could disagree with?
- Is the answer in the first paragraph?
- Is every claim backed by a number, an example, or a link?
- Did you say something honest about a limitation or a competitor's strength?
- Would you send this to an engineer friend without apologizing for it?
- Could a generic SaaS company have published this word for word? If yes, rewrite.
- Did the lint pass clean?
Notes on judgment
Do not fabricate metrics, customer names, or internal data to satisfy the "be specific" rule. If the user has not supplied real numbers, either ask for them or write [X%] placeholders and flag them clearly at the top of the draft. Fake specificity is worse than vagueness, and PostHog's whole style depends on the numbers being real.
Mild profanity appears in real PostHog content and is fine sparingly for punch. It is not a house requirement. Match the user's own register and skip it if unsure.
Surface fixes the register, not taste. A docs page written with newsletter energy is a bad docs page, no matter how good the jokes are.