Knowledge Base Article

Draft a clear, searchable KB article from a resolved support issue or common question. Include problem statement, solution steps, troubleshooting guidance, and related FAQs.

Workflow

Step 1: Extract the Core Problem

Identify what the article should cover:

• Problem statement: What symptom or question does the customer experience?
• Root cause: What causes the problem (if applicable)?
• Frequency: How often does this come up in support? Is it a one-off or recurring pattern?
• Audience: External customers, internal agents, or both?
• Scope: Does this apply to all users or specific plans, roles, or configurations?

Step 2: Document the Solution

Write step-by-step instructions to resolve the issue:

• Prerequisites: What the user needs before starting (permissions, plan tier, access).
• Steps: Numbered, testable actions the user can follow.
• Verification: How the user confirms the solution worked.
• Alternative paths: Different approaches for different environments or configurations.
• Screenshots or examples: Where visual guidance would reduce confusion.

Step 3: Add Troubleshooting

Anticipate what could go wrong:

• Common errors: Error messages the user might encounter during the solution steps.
• Edge cases: Situations where the standard solution does not apply.
• Escalation path: When and how to contact support if self-service fails.
• Related issues: Problems that look similar but have different solutions.

Step 4: Write FAQs

Address questions that commonly follow the main topic:

• Pull from related tickets to identify real customer questions.
• Keep answers concise -- one to three sentences each.
• Link to other articles for topics that deserve their own page.

Step 5: Optimize for Search

Make the article findable:

• Title: Use the words customers actually type (symptom-based, not internal jargon).
• Keywords: Include common search terms, error codes, and feature names.
• Metadata: Category, product area, applicable plan tiers.

Output Format

## KB Article Draft

**Title**: <symptom-based, searchable title>
**Category**: <product area>
**Applies to**: <plan tiers, roles, or "All users">
**Last updated**: <date>

---

### Problem
<1-2 sentence description of the symptom the customer sees>

### Cause
<brief explanation of why this happens, if relevant>

### Solution

**Prerequisites**: <what the user needs before starting>

1. <step one>
2. <step two>
3. <step three>

**Verify**: <how to confirm the fix worked>

### Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| <error or symptom> | <why> | <what to do> |

### FAQ

**Q: <common follow-up question>**
A: <concise answer>

**Q: <another question>**
A: <concise answer>

### Still Need Help?
Contact support at <channel> with <information to include>.

---

**Internal Notes**
- Source ticket(s): <IDs>
- SEO keywords: <search terms>
- Review cycle: <suggested review date>

Examples

User: "Turn ticket #3201 about resetting 2FA into a KB article" Action: Read the resolution from the ticket, write up the steps for customers to reset their own 2FA, add troubleshooting for common errors, include FAQs.

User: "We get five tickets a week about CSV import formatting -- write a help article" Action: Aggregate the common formatting mistakes from recent tickets, document the correct format with examples, add a troubleshooting table for each error message.

User: "Document the workaround for the calendar sync delay as an internal article" Action: Write an agent-facing article with the workaround steps, include the root cause context engineering provided, note the expected permanent fix timeline.

Best Practices

• Write titles as customers would search, not as engineers would name the feature. "Export not working" beats "Data export module error handling."
• Test every step yourself or have an agent walk through them before publishing.
• Use screenshots sparingly. They break when the UI changes and are expensive to maintain.
• Keep the article focused on one problem. If the scope creeps, split into multiple articles.
• Include the error message text verbatim so customers searching for it will find the article.
• Set a review date. Articles that describe workarounds should be revisited when permanent fixes ship.
• Write for scanning: short paragraphs, numbered steps, bold key terms.
• Link related articles bidirectionally so customers can navigate between related topics.
• Note which plan tiers and roles the article applies to upfront to prevent confusion.