kb-authoring

---
name: kb-authoring
description: Author and maintain knowledge base articles derived from resolved support cases. Activate when documenting a solution from a closed ticket, writing how-to guides, building troubleshooting walkthroughs, creating FAQ entries, publishing known-issue advisories, updating stale documentation, organizing KB taxonomy, or performing content gap analysis to reduce future ticket volume.
---

## Article Anatomy

### Mandatory Components

Every knowledge base article includes:

1. **Title**: Outcome-oriented or symptom-oriented. Written in the language a customer would type into a search bar -- never internal jargon.
2. **Summary**: 1-2 plain-language sentences stating what the article covers and who benefits from it.
3. **Content body**: Organized by article type (see below).
4. **Cross-references**: Links to companion articles for adjacent topics.
5. **Metadata**: Category, tags, intended audience, last-modified date.

### Formatting Standards

- **Headings (H2, H3)**: Create a scannable outline so readers can jump to the relevant section.
- **Numbered lists**: For ordered procedures where sequence matters.
- **Bullet lists**: For unordered sets of items or options.
- **Bold text**: For UI labels, critical terms, and points of emphasis.
- **Code blocks**: For commands, API payloads, error strings, and configuration snippets.
- **Tables**: For side-by-side comparisons, option matrices, and reference data.
- **Callouts / admonitions**: For warnings, tips, and must-read caveats.
- **Paragraph length**: Cap at 2-4 sentences. Dense paragraphs drive readers away.
- **Section discipline**: One concept per section. If a section serves two purposes, split it.

## Making Articles Findable

An article that cannot be discovered through search is an article that does not exist.

### Title Construction

| Effective Title | Ineffective Title | Rationale |
|-----------------|-------------------|-----------|
| "Set up SSO with Okta" | "SSO Configuration" | Names the specific tool customers search for |
| "Fix: Dashboard displays blank page" | "Dashboard Problem" | Mirrors the exact symptom customers experience |
| "API rate limits and quota reference" | "API Details" | Contains the precise terms people query |
| "Error: 'Connection refused' during data import" | "Import Errors" | Includes the literal error string customers paste into search |

### Keyword Strategy

- **Embed exact error messages**: Customers frequently paste error text directly into search fields.
- **Write in the customer's dialect**: "can't log in" outperforms "authentication failure" for discoverability.
- **Cover synonyms**: "delete / remove", "home page / dashboard", "download / export".
- **Offer alternate framings**: Address the same problem from multiple angles in the summary.
- **Tag by product surface**: Categories and tags should reflect the customer's mental model, not the engineering org chart.

### Opening Line Patterns

Anchor every article with a first sentence that restates the task or problem in everyday language:

- **Procedural**: "Follow these steps to [accomplish X]."
- **Diagnostic**: "Seeing [symptom]? This article walks through the fix."
- **Factual**: "[Question phrased as a customer would ask]? Here is the answer."
- **Advisory**: "Some users encounter [symptom]. Here is what is happening and how to work around it."

## Article Blueprints

### Procedural (How-To) Articles

**Goal**: Walk a customer through a task from start to finish.

```
# How to [accomplish task]

[Summary: what this covers and when you would need it]

## Before You Begin

- [Prerequisite 1]
- [Prerequisite 2]

## Instructions

### Step 1: [Action verb phrase]
[Precise instruction with path: Settings > Integrations > API Keys]

### Step 2: [Action verb phrase]
[Instruction, including what the user should see after completing this step]

## Confirm Success

[How to verify the task completed correctly]

## Troubleshooting

- [Potential hiccup]: [Resolution]

## See Also

- [Related article links]
```

**Guidance:**
- Open every step with a verb.
- Specify navigation paths explicitly: "Go to Settings > Team > Roles."
- Describe expected outcomes at key checkpoints: "A green banner confirms the save."
- Validate instructions against a recent ticket resolution or by walking through them yourself.

### Diagnostic (Troubleshooting) Articles

**Goal**: Help a customer identify and resolve a specific malfunction.

```
# [Problem statement matching what the user observes]

## What You See

- [Observable symptom 1]
- [Observable symptom 2]

## Why This Happens

[Concise, jargon-free explanation of the root cause]

## How to Fix It

### Fix 1: [Most likely resolution]
[Step-by-step instructions]

### Fix 2: [Alternate resolution if Fix 1 does not apply]
[Step-by-step instructions]

## Preventing Recurrence

[Configuration change or practice that avoids this in the future]

## Need More Help?

[How to contact support]
```

**Guidance:**
- Organize by symptoms first -- that is what customers search for.
- Present the most probable fix before alternatives.
- Always include a "Need more help?" escape hatch pointing to support.
- If the technical cause is complex, keep the customer explanation simple.

### Quick-Answer (FAQ) Articles

**Goal**: Deliver a concise response to a common question.

```
# [Question in the customer's natural phrasing]

[Direct answer: 1-3 sentences]

## Additional Context

[Deeper explanation, edge cases, or nuance if needed]

## Related Questions

- [Link to related FAQ 1]
- [Link to related FAQ 2]
```

**Guidance:**
- Answer the question in the very first sentence.
- If the answer requires a multi-step walkthrough, it belongs in a how-to article, not an FAQ.
- Interlink related FAQs so customers can self-serve adjacent questions.

### Known-Issue Advisories

**Goal**: Document an active bug or limitation along with its current status and any available workaround.

```
# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix Underway / Resolved]
**Who is affected:** [Scope]
**Last updated:** [Date]

## What Users Experience

[Description of the observable behavior]

## Workaround

[Step-by-step workaround, or "No workaround is currently available."]

## Resolution Timeline

[Estimated fix date or current engineering status]

## Change Log

- [Date]: [Update summary]
```

**Guidance:**
- Keep the status field current -- stale status information erodes trust faster than almost anything else.
- Update the article the moment a fix ships and mark it Resolved.
- Leave resolved advisories published for at least 30 days so customers still searching old symptoms can find closure.

## Content Lifecycle and Maintenance

Knowledge bases decay without active stewardship. Follow this cadence:

| Activity | Cadence | Owner |
|----------|---------|-------|
| **Peer review of new articles** | Before every publication | Author + subject-matter expert |
| **High-traffic article accuracy audit** | Quarterly | Support team |
| **Stale content detection** | Monthly | Flag anything untouched for 6+ months |
| **Known-issue status refresh** | Weekly | Update every open advisory |
| **Effectiveness review** | Monthly | Examine helpfulness ratings, bounce rates, and search-to-click ratios |
| **Coverage gap analysis** | Quarterly | Identify top ticket drivers that lack corresponding KB articles |

### Article States

1. **Draft**: Written, pending review
2. **Live**: Published and accessible to customers
3. **Flagged**: Marked for revision due to product changes, user feedback, or age
4. **Archived**: Retired from customer view but retained internally for reference
5. **Deleted**: Permanently removed from the knowledge base

### Update vs. Create Decision Framework

**Revise an existing article when:**
- A product update has changed the steps but the topic is the same
- The article is fundamentally sound but missing a detail
- Customer feedback points to a confusing section
- A superior workaround or solution has been discovered

**Write a new article when:**
- A new feature or product area has no documentation
- A closed ticket reveals a topic with zero KB coverage
- An existing article has grown unwieldy and should be split
- A distinct audience needs the same information presented differently

## Taxonomy and Cross-Linking

### Recommended Category Hierarchy

Structure the knowledge base around how customers navigate, not how the organization is structured:

```
Getting Started
  Account creation and setup
  Initial configuration
  Quickstart walkthroughs

Product Capabilities
  [Capability area A]
  [Capability area B]
  [Capability area C]

Integrations
  [Integration A]
  [Integration B]
  API reference

Problem Solving
  Frequent errors
  Performance and reliability
  Active known issues

Billing and Account Management
  Plans and pricing
  Payment and invoicing
  Account settings
```

### Cross-Linking Principles

- **Diagnostic to procedural**: "For setup instructions, see [How to configure X]."
- **Procedural to diagnostic**: "Running into errors? See [Troubleshooting X]."
- **FAQ to in-depth article**: "For a complete walkthrough, see [Guide to X]."
- **Advisory to workaround**: Minimize the number of clicks between problem identification and resolution.
- **Prefer relative links**: They survive reorganizations better than absolute URLs.
- **Avoid gratuitous circular links**: A linking to B and B linking back to A is only justified when both are genuine entry points.

## Guiding Principles

1. Write for the frustrated customer who is mid-search for an answer -- be direct, specific, and immediately helpful.
2. Every article must be discoverable using the words a real customer would type.
3. Validate your work: follow the steps yourself or have someone unfamiliar with the topic attempt them.
4. Maintain focus: one problem, one resolution per article. Split when scope creeps.
5. Tend the garden aggressively: an outdated article is more harmful than a missing one.
6. Track the gaps: every ticket that could have been deflected by an article represents a content opportunity.
7. Measure outcomes: articles with low traffic, poor ratings, or no ticket-deflection impact need rework or retirement.