If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

/kb-article <resolved issue, ticket reference, or topic description>

• /kb-article How to configure SSO with Okta — resolved this for 3 customers last month

• /kb-article Ticket #4521 — customer couldn't export data over 10k rows

• /kb-article Common question: how to set up webhook notifications

• /kb-article Known issue: dashboard charts not loading on Safari 16

• What was the problem? The original issue, question, or error
• What was the solution? The resolution, workaround, or answer
• Who does this affect? User type, plan level, or configuration
• How common is this? One-off or recurring issue
• What article type fits best? How-to, troubleshooting, FAQ, known issue, or reference (see article types below)

• ~~support platform: Pull the ticket thread, resolution, and any internal notes
• ~~knowledge base: Check if a similar article already exists (update vs. create new)
• ~~project tracker: Check if there's a related bug or feature request

• Follow the template for the chosen article type (how-to, troubleshooting, FAQ, known issue, or reference)
• Apply the searchability best practices: customer-language title, plain-language opening sentence, exact error messages, common synonyms
• Keep it scannable: headers, numbered steps, short paragraphs

• Source: [Ticket #, customer conversation, or internal discussion]
• Existing articles to update: [If this overlaps with existing content]
• Review needed from: [SME or team if technical accuracy needs verification]
• Suggested review date: [When to revisit for accuracy]

undefined

• "Want me to check if a similar article already exists in your ~~knowledge base?"
• "Should I adjust the technical depth for a different audience?"
• "Want me to draft a companion article (e.g., a how-to to go with this troubleshooting guide)?"
• "Should I create an internal-only version with additional technical detail?"

1. Title: Clear, searchable, describes the outcome or problem (not internal jargon)
2. Overview: 1-2 sentences explaining what this article covers and who it's for
3. Body: Structured content appropriate to the article type
4. Related articles: Links to relevant companion content
5. Metadata: Category, tags, audience, last updated date

• Use headers (H2, H3) to break content into scannable sections
• Use numbered lists for sequential steps
• Use bullet lists for non-sequential items
• Use bold for UI element names, key terms, and emphasis
• Use code blocks for commands, API calls, error messages, and configuration values
• Use tables for comparisons, options, or reference data
• Use callouts/notes for warnings, tips, and important caveats
• Keep paragraphs short — 2-4 sentences max
• One idea per section — if a section covers two topics, split it

• Include exact error messages — customers copy-paste error text into search
• Use customer language, not internal terminology — "can't log in" not "authentication failure"
• Include common synonyms — "delete/remove", "dashboard/home page", "export/download"
• Add alternate phrasings — address the same issue from different angles in the overview
• Tag with product areas — make sure category and tags match how customers think about the product

• How-to: "This guide shows you how to [accomplish X]."
• Troubleshooting: "If you're seeing [symptom], this article explains how to fix it."
• FAQ: "[Question in the customer's words]? Here's the answer."
• Known issue: "Some users are experiencing [symptom]. Here's what we know and how to work around it."

• [What's needed before starting]

• [Links]

**Best practices**:
- Start each step with a verb
- Include the specific path: "Go to Settings > Integrations > API Keys"
- Mention what the user should see after each step ("You should see a green confirmation banner")
- Test the steps yourself or verify with a recent ticket resolution

• [What the user observes]

• [Link to related FAQ]
• [Link to related FAQ]

**Best practices**:
- Answer the question in the first sentence
- Keep it concise — if the answer needs a walkthrough, it's a how-to, not an FAQ
- Group related FAQs and link between them

1. Draft: Written, needs review
2. Published: Live and available to customers
3. Needs update: Flagged for revision (product change, feedback, or age)
4. Archived: No longer relevant but preserved for reference
5. Retired: Removed from the knowledge base

• The product changed and steps need refreshing
• The article is mostly right but missing a detail
• Feedback indicates customers are confused by a specific section
• A better workaround or solution was found

• A new feature or product area needs documentation
• A resolved ticket reveals a gap — no article exists for this topic
• The existing article covers too many topics and should be split
• A different audience needs the same information explained differently

• Link from troubleshooting to how-to: "For setup instructions, see [How to configure X]"
• Link from how-to to troubleshooting: "If you encounter errors, see [Troubleshooting X]"
• Link from FAQ to detailed articles: "For a full walkthrough, see [Guide to X]"
• Link from known issues to workarounds: Keep the chain from problem to solution short
• Use relative links within the KB — they survive restructuring better than absolute URLs
• Avoid circular links — if A links to B, B shouldn't link back to A unless both are genuinely useful entry points

1. Write for the customer who is frustrated and searching for an answer — be clear, direct, and helpful
2. Every article should be findable through search using the words a customer would type
3. Test your articles — follow the steps yourself or have someone unfamiliar with the topic follow them
4. Keep articles focused — one problem, one solution. Split if an article is growing too long
5. Maintain aggressively — a wrong article is worse than no article
6. Track what's missing — every ticket that could have been a KB article is a content gap
7. Measure impact — articles that don't get traffic or don't reduce tickets need to be improved or retired