Kb Article

# /kb-article

> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../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

| Good Title | Bad Title | Why | |------------|-----------|-----| | "How to configure SSO with Okta" | "SSO Setup" | Specific, includes the tool name customers search for | | "Fix: Dashboard shows blank page" | "Dashboard Issue" | Includes the symptom customers experience | | "API rate limits and quotas" | "API Information" | Includes the specific terms customers search for | | "Error: 'Connection refused' when importing data" | "Import Problems" | Includes the exact error message |

### 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 alt