Kb Article

/kb-article

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

Draft a publish-ready knowledge base article from a resolved support issue, common question, or documented workaround. Structures the content for searchability and self-service.

Usage

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

Examples:

• /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

Workflow

1. Understand the Source Material

Parse the input to identify:

• 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)

If a ticket reference is provided, look up the full context:

• ~~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

2. Draft the Article

Using the article structure, formatting standards, and searchability best practices below:

• 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

3. Generate the Article

Present the draft with metadata:

## KB Article Draft

**Title:** [Article title]
**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]
**Category:** [Product area or topic]
**Tags:** [Searchable tags]
**Audience:** [All users / Admins / Developers / Specific plan]

---

[Full article content — using the appropriate template below]

---

### Publishing Notes
- **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]

4. Offer Next Steps

After generating the article:

• "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?"

Article Structure and Formatting Standards

Universal Article Elements

Every KB article should include:

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

Formatting Rules

• 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

Writing for Searchability

Articles are useless if customers can't find them. Optimize every article for search:

Title Best Practices

Keyword Optimization

• 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

Opening Sentence Formula

Start every article with a sentence that restates the problem or task in plain language:

• 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."

Article Type Templates

How-to Articles

Purpose: Step-by-step instructions for accomplishing a task.

Structure:

# How to [accomplish task]

[Overview — what this guide covers and when you'd use it]

## Prerequisites
- [What's needed before starting]

## Steps
### 1. [Action]
[Instruction with specific details]

### 2. [Action]
[Instruction]

## Verify It Worked
[How to confirm success]

## Common Issues
- [Issue]: [Fix]

## Related Articles
- [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

Troubleshooting Articles

Purpose: Diagnose and resolve a specific problem.

Structure:

# [Problem description — what the user sees]

## Symptoms
- [What the user observes]

## Cause
[Why this happens — brief, non-jargon explanation]

## Solution
### Option 1: [Primary fix]
[Steps]

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

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

## Still Having Issues?
[How to get help]

Best practices:

• Lead with symptoms, not causes — customers search for what they see
• Provide multiple solutions when possible (most likely fix first)
• Include a "Still having issues?" section that points to support
• If the root cause is complex, keep the customer-facing explanation simple

FAQ Articles

Purpose: Quick answer to a common question.

Structure:

# [Question — in the customer's words]

[Direct answer — 1-3 sentences]

## Details
[Additional context, nuance, or explanation if needed]

## Related Questions
- [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

Known Issue Articles

Purpose: Document a known bug or limitation with a workaround.

Structure:

# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]
**Affected:** [Who/what is affected]
**Last updated:** [Date]

## Symptoms
[What users experience]

## Workaround