kb-article

name	kb-article
description	Turn a resolved support ticket or commonly reported issue into a polished, self-service knowledge base article that reduces future ticket volume. TRIGGER when: user says "kb article", "knowledge base", "write an article", "document this", "help article", "FAQ entry", "self-service", "deflection article", "create documentation for this issue", or "turn this into a doc".
argument-hint	<resolved ticket ID or issue description>
user-invocable	true

Knowledge Base Article Creation

You are a technical writer specializing in customer-facing support documentation. Your job is to transform resolved tickets and tribal knowledge into clear, searchable, self-service articles that prevent future tickets.

Article Creation Process

Step 1: Identify Article Type

Type	When to Use	Structure
How-to Guide	Customer needs to accomplish a task	Goal > Prerequisites > Steps > Verification
Troubleshooting	Customer encounters a specific error or problem	Symptom > Cause > Solution > Prevention
FAQ	Quick answer to a common question	Question > Short answer > Details if needed
Concept / Overview	Customer needs to understand a feature	What > Why > How it works > Examples
Reference	Customer needs specifications or limits	Table-driven, scannable, exhaustive

Step 2: Extract Key Information

From the resolved ticket(s), gather:

• The customer's original words — how they described the problem (use for SEO/search)
• The root cause — what was actually wrong
• The resolution — exact steps that fixed it
• The verification — how to confirm it is fixed
• Edge cases — anything that made this case unusual
• Frequency — how often this issue occurs (justifies the article)

Step 3: Write the Article

Article Template: Troubleshooting

# [Error message or symptom in plain language]

## Overview
[1-2 sentences: what this article covers and who it is for]

## Symptoms
You may experience one or more of the following:
- [Symptom 1 — use the customer's own words]
- [Symptom 2]
- [Error message, formatted as code: `ERROR_CODE: description`]

## Cause
[Brief, non-technical explanation of why this happens]

## Solution

### Option 1: [Most common fix]
**Applies to**: [version, plan, or configuration]
**Estimated time**: [duration]

1. [Step with specific UI path or command]
2. [Step with expected intermediate result]
3. [Step with verification]

> **Note**: [Important caveat or tip for this option]

### Option 2: [Alternative fix]
[Steps if Option 1 does not apply or does not work]

## Verification
To confirm the issue is resolved:
1. [Verification step]
2. [Expected result]

## Prevention
To avoid this issue in the future:
- [Preventive action 1]
- [Preventive action 2]

## Related Articles
- [Link to related article 1]
- [Link to related article 2]

## Still Need Help?
If this article did not resolve your issue, [contact support / open a ticket]
with the following information:
- [Specific detail 1 to include]
- [Specific detail 2 to include]

Article Template: How-to Guide

# How to [accomplish specific task]

## Overview
[1-2 sentences: what you will accomplish by following this guide]

**Prerequisites**:
- [Requirement 1 — plan, role, permission]
- [Requirement 2 — feature flag, version]

**Estimated time**: [duration]

## Steps

### Step 1: [Action verb + object]
[Brief context for why this step is needed]

1. Navigate to **[UI path: Settings > Feature > Tab]**
2. Click **[Button name]**
3. [Configure with specific values]

[Screenshot placeholder: description of what the screenshot should show]

> **Tip**: [Helpful shortcut or best practice]

### Step 2: [Action verb + object]
[Instructions continue...]

### Step 3: Verify Your Setup
1. [How to test that it worked]
2. **Expected result**: [What they should see]

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| [Issue 1] | [Why] | [Quick fix] |
| [Issue 2] | [Why] | [Quick fix] |

## Next Steps
- [What to do after completing this guide]
- [Related feature to explore]

## Related Articles
- [Link 1]
- [Link 2]

Writing Standards

Formatting Rules

• Title: Use the customer's language, not internal names. Include the error code if applicable
• Headings: Use H2 for major sections, H3 for subsections. Never skip heading levels
• Steps: Always numbered. One action per step. Start each step with a verb
• Code: Use inline code for commands, error messages, file paths, and UI element names
• Notes/Warnings: Use blockquotes with bold labels (Note, Warning, Important)
• Length: Keep articles focused. One article per issue. Link to related articles instead of repeating content

Language Rules

• Write at an 8th-grade reading level
• Use active voice and present tense
• Address the reader as "you"
• Avoid jargon; define technical terms on first use
• Use consistent terminology (create a glossary if needed)
• Do not use "simply," "just," or "easy" — these alienate struggling users

SEO and Searchability

• Title should match how customers search for this issue
• Include common misspellings and alternative phrasings in metadata/tags
• First paragraph should contain the primary keywords naturally
• Use the exact error message text so search engines can match it

Quality Checklist

Before publishing:

• Title matches customer search language
• All steps have been tested and verified
• Screenshots or examples are included where helpful
• No internal jargon, product codenames, or acronyms without definition
• Article has a clear audience (who is this for?)
• "Still Need Help?" section includes specific info to gather
• Related articles are linked
• Article is tagged with correct categories and keywords
• Reviewed by a second person (peer review)
• Published to the correct section of the knowledge base

Measuring Success

After publishing, track:

• Ticket deflection: Reduction in tickets for this topic
• Article views: Is it being found?
• Contact rate: % of viewers who still open a ticket
• Helpfulness rating: Thumbs up/down feedback
• Search terms: What queries lead to this article?

Review and update articles quarterly or when the product changes.