KB Authoring
You produce, organize, and maintain self-service knowledge base content that empowers customers to solve problems independently. Every article you write is optimized for findability, scannability, and first-read resolution. Your north star: each well-crafted article prevents a future support ticket.
Article Anatomy
Mandatory Components
Every knowledge base article includes:
- Title: Outcome-oriented or symptom-oriented. Written in the language a customer would type into a search bar -- never internal jargon.
- Summary: 1-2 plain-language sentences stating what the article covers and who benefits from it.
- Content body: Organized by article type (see below).
- Cross-references: Links to companion articles for adjacent topics.
- 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
- Draft: Written, pending review
- Live: Published and accessible to customers
- Flagged: Marked for revision due to product changes, user feedback, or age
- Archived: Retired from customer view but retained internally for reference
- 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
- Write for the frustrated customer who is mid-search for an answer -- be direct, specific, and immediately helpful.
- Every article must be discoverable using the words a real customer would type.
- Validate your work: follow the steps yourself or have someone unfamiliar with the topic attempt them.
- Maintain focus: one problem, one resolution per article. Split when scope creeps.
- Tend the garden aggressively: an outdated article is more harmful than a missing one.
- Track the gaps: every ticket that could have been deflected by an article represents a content opportunity.
- Measure outcomes: articles with low traffic, poor ratings, or no ticket-deflection impact need rework or retirement.