knowledge-base

name	knowledge-base
version	0.1.0
description	Use this skill when designing help center architecture, writing support articles, or optimizing search and self-service. Triggers on knowledge base, help center, support articles, self-service, article templates, search optimization, content taxonomy, and any task requiring help documentation design or management.
tags	["knowledge-base","help-center","self-service","articles","documentation","experimental-design","writing","performance","search"]
category	operations
recommended_skills	["customer-support-ops","internal-docs","technical-writing","second-brain"]
platforms	["claude-code","gemini-cli","openai-codex"]
license	MIT
maintainers	[{"github":"maddhruv"}]

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