Kb Article

1---2name: kb-article3description: Draft a knowledge base article from a resolved issue or common question. Use when a ticket resolution is worth documenting for self-service, the same question keeps coming up, a workaround needs to be published, or a known issue should be communicated to customers.4argument-hint: "<resolved issue or ticket>"5---6 7# /kb-article8 9> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).10 11Draft a publish-ready knowledge base article from a resolved support issue, common question, or documented workaround. Structures the content for searchability and self-service.12 13## Usage14 15```16/kb-article <resolved issue, ticket reference, or topic description>17```18 19Examples:20- `/kb-article How to configure SSO with Okta — resolved this for 3 customers last month`21- `/kb-article Ticket #4521 — customer couldn't export data over 10k rows`22- `/kb-article Common question: how to set up webhook notifications`23- `/kb-article Known issue: dashboard charts not loading on Safari 16`24 25## Workflow26 27### 1. Understand the Source Material28 29Parse the input to identify:30 31- **What was the problem?** The original issue, question, or error32- **What was the solution?** The resolution, workaround, or answer33- **Who does this affect?** User type, plan level, or configuration34- **How common is this?** One-off or recurring issue35- **What article type fits best?** How-to, troubleshooting, FAQ, known issue, or reference (see article types below)36 37If a ticket reference is provided, look up the full context:38 39- **~~support platform**: Pull the ticket thread, resolution, and any internal notes40- **~~knowledge base**: Check if a similar article already exists (update vs. create new)41- **~~project tracker**: Check if there's a related bug or feature request42 43### 2. Draft the Article44 45Using the article structure, formatting standards, and searchability best practices below:46 47- Follow the template for the chosen article type (how-to, troubleshooting, FAQ, known issue, or reference)48- Apply the searchability best practices: customer-language title, plain-language opening sentence, exact error messages, common synonyms49- Keep it scannable: headers, numbered steps, short paragraphs50 51### 3. Generate the Article52 53Present the draft with metadata:54 55```56## KB Article Draft57 58**Title:** [Article title]59**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]60**Category:** [Product area or topic]61**Tags:** [Searchable tags]62**Audience:** [All users / Admins / Developers / Specific plan]63 64---65 66[Full article content — using the appropriate template below]67 68---69 70### Publishing Notes71- **Source:** [Ticket #, customer conversation, or internal discussion]72- **Existing articles to update:** [If this overlaps with existing content]73- **Review needed from:** [SME or team if technical accuracy needs verification]74- **Suggested review date:** [When to revisit for accuracy]75```76 77### 4. Offer Next Steps78 79After generating the article:80- "Want me to check if a similar article already exists in your ~~knowledge base?"81- "Should I adjust the technical depth for a different audience?"82- "Want me to draft a companion article (e.g., a how-to to go with this troubleshooting guide)?"83- "Should I create an internal-only version with additional technical detail?"84 85---86 87## Article Structure and Formatting Standards88 89### Universal Article Elements90 91Every KB article should include:92 931. **Title**: Clear, searchable, describes the outcome or problem (not internal jargon)942. **Overview**: 1-2 sentences explaining what this article covers and who it's for953. **Body**: Structured content appropriate to the article type964. **Related articles**: Links to relevant companion content975. **Metadata**: Category, tags, audience, last updated date98 99### Formatting Rules100 101- **Use headers (H2, H3)** to break content into scannable sections102- **Use numbered lists** for sequential steps103- **Use bullet lists** for non-sequential items104- **Use bold** for UI element names, key terms, and emphasis105- **Use code blocks** for commands, API calls, error messages, and configuration values106- **Use tables** for comparisons, options, or reference data107- **Use callouts/notes** for warnings, tips, and important caveats108- **Keep paragraphs short** — 2-4 sentences max109- **One idea per section** — if a section covers two topics, split it110 111## Writing for Searchability112 113Articles are useless if customers can't find them. Optimize every article for search:114 115### Title Best Practices116 117| Good Title | Bad Title | Why |118|------------|-----------|-----|119| "How to configure SSO with Okta" | "SSO Setup" | Specific, includes the tool name customers search for |120| "Fix: Dashboard shows blank page" | "Dashboard Issue" | Includes the symptom customers experience |121| "API rate limits and quotas" | "API Information" | Includes the specific terms customers search for |122| "Error: 'Connection refused' when importing data" | "Import Problems" | Includes the exact error message |123 124### Keyword Optimization125 126- **Include exact error messages** — customers copy-paste error text into search127- **Use customer language**, not internal terminology — "can't log in" not "authentication failure"128- **Include common synonyms** — "delete/remove", "dashboard/home page", "export/download"129- **Add alternate phrasings** — address the same issue from different angles in the overview130- **Tag with product areas** — make sure category and tags match how customers think about the product131 132### Opening Sentence Formula133 134Start every article with a sentence that restates the problem or task in plain language:135 136- **How-to**: "This guide shows you how to [accomplish X]."137- **Troubleshooting**: "If you're seeing [symptom], this article explains how to fix it."138- **FAQ**: "[Question in the customer's words]? Here's the answer."139- **Known issue**: "Some users are experiencing [symptom]. Here's what we know and how to work around it."140 141## Article Type Templates142 143### How-to Articles144 145**Purpose**: Step-by-step instructions for accomplishing a task.146 147**Structure**:148```149# How to [accomplish task]150 151[Overview — what this guide covers and when you'd use it]152 153## Prerequisites154- [What's needed before starting]155 156## Steps157### 1. [Action]158[Instruction with specific details]159 160### 2. [Action]161[Instruction]162 163## Verify It Worked164[How to confirm success]165 166## Common Issues167- [Issue]: [Fix]168 169## Related Articles170- [Links]171```172 173**Best practices**:174- Start each step with a verb175- Include the specific path: "Go to Settings > Integrations > API Keys"176- Mention what the user should see after each step ("You should see a green confirmation banner")177- Test the steps yourself or verify with a recent ticket resolution178 179### Troubleshooting Articles180 181**Purpose**: Diagnose and resolve a specific problem.182 183**Structure**:184```185# [Problem description — what the user sees]186 187## Symptoms188- [What the user observes]189 190## Cause191[Why this happens — brief, non-jargon explanation]192 193## Solution194### Option 1: [Primary fix]195[Steps]196 197### Option 2: [Alternative if Option 1 doesn't work]198[Steps]199 200## Prevention201[How to avoid this in the future]202 203## Still Having Issues?204[How to get help]205```206 207**Best practices**:208- Lead with symptoms, not causes — customers search for what they see209- Provide multiple solutions when possible (most likely fix first)210- Include a "Still having issues?" section that points to support211- If the root cause is complex, keep the customer-facing explanation simple212 213### FAQ Articles214 215**Purpose**: Quick answer to a common question.216 217**Structure**:218```219# [Question — in the customer's words]220 221[Direct answer — 1-3 sentences]222 223## Details224[Additional context, nuance, or explanation if needed]225 226## Related Questions227- [Link to related FAQ]228- [Link to related FAQ]229```230 231**Best practices**:232- Answer the question in the first sentence233- Keep it concise — if the answer needs a walkthrough, it's a how-to, not an FAQ234- Group related FAQs and link between them235 236### Known Issue Articles237 238**Purpose**: Document a known bug or limitation with a workaround.239 240**Structure**:241```242# [Known Issue]: [Brief description]243 244**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]245**Affected:** [Who/what is affected]246**Last updated:** [Date]247 248## Symptoms249[What users experience]250 251## Workaround252[Steps to work around the issue, or "No workaround available"]253 254## Fix Timeline255[Expected fix date or current status]256 257## Updates258- [Date]: [Update]259```260 261**Best practices**:262- Keep the status current — nothing erodes trust faster than a stale known issue article263- Update the article when the fix ships and mark as resolved264- If resolved, keep the article live for 30 days for customers still searching the old symptoms265 266## Review and Maintenance Cadence267 268Knowledge bases decay without maintenance. Follow this schedule:269 270| Activity | Frequency | Who |271|----------|-----------|-----|272| **New article review** | Before publishing | Peer review + SME for technical content |273| **Accuracy audit** | Quarterly | Support team reviews top-traffic articles |274| **Stale content check** | Monthly | Flag articles not updated in 6+ months |275| **Known issue updates** | Weekly | Update status on all open known issues |276| **Analytics review** | Monthly | Check which articles have low helpfulness ratings or high bounce rates |277| **Gap analysis** | Quarterly | Identify top ticket topics without KB articles |278 279### Article Lifecycle280 2811. **Draft**: Written, needs review2822. **Published**: Live and available to customers2833. **Needs update**: Flagged for revision (product change, feedback, or age)2844. **Archived**: No longer relevant but preserved for reference2855. **Retired**: Removed from the knowledge base286 287### When to Update vs. Create New288 289**Update existing** when:290- The product changed and steps need refreshing291- The article is mostly right but missing a detail292- Feedback indicates customers are confused by a specific section293- A better workaround or solution was found294 295**Create new** when:296- A new feature or product area needs documentation297- A resolved ticket reveals a gap — no article exists for this topic298- The existing article covers too many topics and should be split299- A different audience needs the same information explained differently300 301## Linking and Categorization Taxonomy302 303### Category Structure304 305Organize articles into a hierarchy that matches how customers think:306 307```308Getting Started309├── Account setup310├── First-time configuration311└── Quick start guides312 313Features & How-tos314├── [Feature area 1]315├── [Feature area 2]316└── [Feature area 3]317 318Integrations319├── [Integration 1]320├── [Integration 2]321└── API reference322 323Troubleshooting324├── Common errors325├── Performance issues326└── Known issues327 328Billing & Account329├── Plans and pricing330├── Billing questions331└── Account management332```333 334### Linking Best Practices335 336- **Link from troubleshooting to how-to**: "For setup instructions, see [How to configure X]"337- **Link from how-to to troubleshooting**: "If you encounter errors, see [Troubleshooting X]"338- **Link from FAQ to detailed articles**: "For a full walkthrough, see [Guide to X]"339- **Link from known issues to workarounds**: Keep the chain from problem to solution short340- **Use relative links** within the KB — they survive restructuring better than absolute URLs341- **Avoid circular links** — if A links to B, B shouldn't link back to A unless both are genuinely useful entry points342 343## KB Writing Best Practices344 3451. Write for the customer who is frustrated and searching for an answer — be clear, direct, and helpful3462. Every article should be findable through search using the words a customer would type3473. Test your articles — follow the steps yourself or have someone unfamiliar with the topic follow them3484. Keep articles focused — one problem, one solution. Split if an article is growing too long3495. Maintain aggressively — a wrong article is worse than no article3506. Track what's missing — every ticket that could have been a KB article is a content gap3517. Measure impact — articles that don't get traffic or don't reduce tickets need to be improved or retired