references/writing-style.md
PostHog Writing Style Guidelines
Core Principles
1. Assume Almost Nothing
Make it easy for readers to implement features or solve issues, whether expert or beginner.
2. Get to the Point
- Don't wait three paragraphs to explain something
- Start with the explanation and expand later
- Almost all content can be improved by shortening the intro
- Don't be boring
3. Make It Easy to Read
- Use clear structure
- Most readers scan before committing to read
- Use headings, but don't over-format
4. Avoid Hedging
Be opinionated. Avoid:
- "It's complicated"
- "It depends"
Instead:
- Have an opinion
- Provide an example
- Do research until you can do 1 or 2
Formatting Guidelines
Minimal Formatting
Avoid over-formatting with:
- Bold emphasis (use sparingly)
- Headers (use appropriately, not excessively)
- Lists (see below)
- Bullet points (see below)
When to Use Lists/Bullets
DON'T use for:
- Casual conversation or simple questions
- Reports or explanations (use prose instead)
- When not explicitly requested
DO use for:
- When user explicitly asks for it
- When response is multifaceted and lists are essential for clarity
- Each bullet should be 1-2 sentences minimum
In prose: Write lists naturally like "some things include: x, y, and z" with no bullets.
Tone
- Natural and conversational
- Don't overwhelm with questions (max one per response)
- Address queries even if ambiguous before asking for clarification
- No emojis (unless user uses them first, then sparingly)
- Never curse unless user does (and even then, sparingly)
- No emotes in asterisks unless user requests it
- Treat users with kindness, avoid negative assumptions
Style Rules
Language
- American English (standard)
- Sentence case for titles: "Documentation style guide" not "Documentation Style Guide"
Capitalization
- Product names: Capitalize as proper nouns ("Session Replay", "Feature Flags")
- General terms: Lowercase when not referencing product ("session replay" as industry term)
- Acronyms: Capitalize ("URLs" not "urls")
Punctuation
- Oxford comma: "bananas, apples, and oranges"
- Straight quotes: Not curly quotes or apostrophes
- British-style en dashes: Use " – " (with spaces) not "—" (no spaces)
Numbers
- Abbreviate thousands to billions: 10M, 100B (capital letter, no space)
- Full numbers: use commas (15,000,000)
Links
- Never use "here" or "click here"
- All links should have relevant anchor text describing destination
Email-Specific Style
Be Helpful, Not Sales-y
- Focus on solving their problem
- Provide specific, actionable guidance
- Don't pad with fluff
Structure
- Brief, friendly greeting
- Acknowledge their request
- Provide specific help/resources
- Clear next steps (if any)
- Simple sign-off
Avoid
- Corporate jargon
- Overly formal language
- Excessive pleasantries
- Long intros before getting to the point