kb-authoring

What this skill does

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

Stru