mongo-ai/posthog-kb-article

PostHog KB article / docs update skill

When to use

• A resolved ticket reveals a docs gap (customer couldn't find the answer)
• The same issue has come up 2+ times and there's no documentation
• A workaround exists but isn't documented
• A known issue needs a public-facing article
• Docs exist but are misleading, incomplete, or outdated

Workflow

1. Determine article type

| Type | When | Template | |------|------|----------| | Docs update | Existing docs page is incomplete or misleading | Suggest specific edits to the existing page | | Troubleshooting guide | Common problem with diagnostic steps | Symptom → Cause → Solution → Prevention | | How-to | Common setup/config question | Prerequisites → Steps → Verification | | Known issue | Confirmed bug with workaround or timeline | Status → Symptoms → Workaround → Fix timeline |

2. Identify the source

From the triage report, extract:

• What the customer was trying to do
• What went wrong and why
• What the resolution was
• What docs they likely searched (and didn't find)

3. Draft the article

Troubleshooting guide template

# [Problem description — what the user sees]

## Symptoms
- [What the user observes — use their language, not internal jargon]

## Cause
[Brief, plain-language explanation of why this happens]

## Solution

### Option 1: [Primary fix]
1. [Step with exact UI path or code]
2. [Step]
3. [Verification — how to confirm it's fixed]

### Option 2: [Alternative if Option 1 doesn't work]
1. [Step]
2. [Step]

## Prevention
[How to avoid this in the future]

## Still having issues?
[Contact support — link to PostHog support page]

How-to template

# How to [accomplish task]

[1-2 sentence overview of what this covers and when you'd use it]

## Prerequisites
- [What's needed before starting — SDK version, plan tier, etc.]

## Steps

### 1. [Action]
[Instruction with specific UI path or code snippet]

### 2. [Action]
[Instruction]

## Verify it worked
[How to confirm success — what to check in PostHog UI or events]

## Common issues
- **[Issue]**: [Fix]
- **[Issue]**: [Fix]

Known issue template

# Known issue: [Brief description]

**Status:** [Investigating / Workaround available / Fix in progress / Fixed in vX.Y.Z]
**Affected:** [SDK versions, platforms, plan tiers]
**Last updated:** [Date]

## Symptoms
[What users experience]

## Workaround
[Steps to work around the issue — or "No workaround available"]

## Fix timeline
[When the fix is expected or what version it shipped in]

## Updates
- [Date]: [Update]

4. Searchability checklist

Before finalizing:

• [ ] Title uses customer language, not internal jargon
• [ ] Title includes the exact symptom or error message
• [ ] Opening sentence restates the problem in plain language
• [ ] Common synonyms are included (e.g., "delete/remove", "can't see/missing")
• [ ] SDK/platform versions are mentioned where relevant
• [ ] Exact error messages are included if applicable

5. Output format

## KB Article Suggestion

**Type:** [Docs update / Troubleshooting / How-to / Known issue]
**Target:** [Existing docs page URL to update, or "New article"]
**Product area:** [events / replay / flags / experiments / error tracking / surveys / pipelines]
**Source ticket:** [ticket reference from triage report]

---

[Full article draft]

---

**Why this matters:** [How many customers this could help / how often this comes up]
**Repo for PR:** [PostHog/posthog.com for docs, or PostHog/posthog for in-app help]

Rules

• Write for frustrated customers searching for answers — be clear and direct
• Use the customer's terminology, not PostHog internal naming
• Include exact UI paths: "Go to Settings > Session Replay > check 'Enable recording'"
• Include code snippets where relevant
• Link to related PostHog docs pages
• Every article should be findable via the words a customer would type into search
• Don't document temporary workarounds without noting the fix timeline