knowledge-base

Files (6)

• README.md
• SKILL.md
• evals.json
• article-templates.md · references/
• help-center-architecture.md · references/
• search-optimization.md · references/

SKILL.md (first lines)

## Key principles

1. **Write for scanning, not reading** - Users arrive with a specific problem and scan
   for the answer. Use short paragraphs, numbered steps, bold key terms, and clear
   headings. A wall of prose is an article no one reads. Every section should be
   findable with a 2-second scan.

2. **Structure mirrors the user's mental model** - Organize content around tasks users
   are trying to complete and problems they experience, not around your product's
   internal feature structure. "How do I invite a teammate?" beats "User Management >
   Invitations > Creating Invitations." Users think in outcomes, not menus.

3. **Search is the primary navigation** - Most users will never browse your category
   tree. They will type a query and click the first plausible result. Every article
   title, summary, and keyword set must be optimized for the words users actually type,
   not the words your product team uses internally.

4. **Measure deflection, not pageviews** - Pageviews tell you what people look at.
   Deflection tells you whether it worked. Track ticket volume versus help center
   traffic, article ratings, failed searches, and contact-us clicks post-article-view.
   A high-traffic article with a high contact-us rate is a failing article.

5. **Maintain ruthlessly** - An outdated article is worse than no article. It creates
   false confidence and support tickets filled with "I followed the article and it
   didn't work." Every article needs an owner, a review date, and a clear process for
   marking it outdated or archiving it when the feature changes.

---

## Core concepts

### Information architecture

Information architecture (IA) is how content is organized, labeled, and linked. A good
IA means users can find answers in two clicks or fewer from the help center home page.

**Taxonomy design principles:**

- Top-level categories map to user goals, not product features
- 5-8 top-level categories is the practical maximum before navigation becomes overwhelming
- Each article belongs to exactly one primary category (cross-links are fine; dual-homing creates maintenance debt)
- Category names use plain language: "Billing & Payments" beats "Revenue Operations"
- Sub-categories add one level of specificity - avoid nesting beyond two levels

**Taxonomy validation test:** Show the category structure to five users who have never
seen it. Ask them where they would look for a specific common task. If fewer than four
out of five find the right category, redesign the labels.

### Article types

| Type | Purpose | Primary user intent |
|---|---|---|
| How-to | Step-by-step instructions for a task | "I want to do X" |
| Troubleshooting | Diagnose and fix a specific error or symptom | "X is broken or not working" |
| FAQ | Short answers to common questions | "I have a quick question about X" |
| Reference | Complete spec, options table, or glossary | "I need to know all the values/settings for X" |
| Concept | Explains a feature or workflow at a high level | "I want to understand how X works before I use it" |

Most articles should be how-to or troubleshooting. If your knowledge base is mostly
concept articles, users are not finding actionable answers - they are being educated
when they want to be unblocked.

### Search optimization

Search in a knowledge base is keyword-matching plus ranking, not semantic understanding
(even with AI-powered search, explicit optimization still wins).

**The three-layer keyword strategy:**

```
Layer 1 - Title keywords:  Words users type when they know what they want
                           ("reset password", "cancel subscription", "export CSV")

Layer 2 - Synonyms:        Alternate terms for the same concept
                           ("reset" = "forgot", "change", "recover")
                           ("cancel" = "delete account", "close account", "unsubscribe")

Layer 3 - Error strings:   Exact error messages users copy-paste into search
                           ("Error 403: Forbidden", "SMTP authentication failed")
```

Store synonyms in your search tool's synonym dictionary so both terms resolve to the
same results. Never make users guess the "right" terminology.

### Deflection metrics

Deflection is the percentage of users who find an answer in the knowledge base and
do not open a support ticket. It is the primary health metric for a knowledge base.

**Deflection rate formula:**

```
Deflection rate = 1 - (tickets opened after KB visit / total KB visits)
```

**Supporting metrics to track:**

| Metric | What it measures | Healthy target |
|---|---|---|
| Deflection rate | Overall KB effectiveness | > 70% |
| Article rating (thumbs) | Per-article satisfaction | > 80% positive |
| Failed search rate | Queries returning zero results | < 10% |
| Contact-us click rate post-article | Articles that fail to resolve | < 5% per article |
| Article staleness (days since reviewed) | Content freshness | < 180 days |
| Search-to-click rate | How often search results get clicked | > 60% |

---

## Common tasks

### Design help center architecture - taxonomy

**Step 1: Mine your ticket data**

Pull 90 days of support tickets and tag each with the user's underlying goal (not
the feature involved). The top 10 goals by volume become your category candidates.

**Step 2: Card-sort validation**

From mkurman/zorai, MIT.

More from mkurman/zorai