Knowledge Best Practices

Build a knowledge base that helps AI agents

Build a knowledge base that helps your AI agents to deliver accurate, helpful responses. This guide covers content strategy, organization, and maintenance.

Why Knowledge Quality Matters

Your AI agents are only as good as the knowledge they have access to:

Knowledge quality	Result
Accurate knowledge	Accurate answers
Complete knowledge	Higher resolution rates
Well-organized knowledge	Faster retrieval
Up-to-date knowledge	Fewer escalations

---

Content Strategy

Document Types to Include

Type	Examples	Priority
FAQs	Common questions and answers	High
How-To Guides	Step-by-step instructions	High
Troubleshooting	Problem-solution pairs	High
Feature Documentation	Capabilities and usage	Medium
Policies	Terms, procedures, rules	Medium
Concepts	Explanations of key ideas	Low

Document Types to Avoid

Type	Why
Marketing copy	Promotional, not informative
Internal memos	Not relevant to users
Outdated versions	Causes confusion
Duplicate content	Reduces retrieval quality
Raw data dumps	Hard to process

---

Writing for AI Retrieval

Clear Titles

The title is crucial for retrieval:

Weak:

Document #47

Strong:

How to Reset Your Password

Answer-First Structure

Put the answer at the beginning:

Weak:

Password Reset Guide

Passwords are an important security feature. They protect your account
from unauthorized access. In this guide, we'll cover password policies...

[500 words later]

To reset your password:
1. Go to Settings
2. Click "Reset Password"

Strong:

How to Reset Your Password

To reset your password:
1. Go to Settings
2. Click "Reset Password"
3. Enter your email
4. Follow the link sent to your inbox

Additional Information:
- Passwords must be at least 8 characters
- Links expire after 24 hours

Self-Contained Sections

Each section should make sense on its own:

Weak:

As mentioned above, this requires the previous step to be completed.

Strong:

Prerequisites:
- Active account
- Admin permissions

Steps:
1. Navigate to Settings...

---

Organization

Hierarchical Structure

Organize documents logically:

Naming Conventions

Use consistent naming:

Pattern	Example
How to [action]	How to Export Reports
[Topic] Overview	Billing Overview
Troubleshooting [issue]	Troubleshooting Login Errors
[Feature] Configuration	API Configuration

Tagging Strategy

Apply tags consistently:

Document: How to Reset Password
Tags: [password, security, account, reset, self-service]

Tags improve retrieval for related queries.

---

Content Quality

Quality Checklist

For each document:

• Title accurately describes content
• Content answers a specific question
• Information is current and accurate
• Steps are clear and complete
• No broken links or references
• Consistent formatting throughout

Using Quality Scoring

Enable AI quality analysis:

1. Navigate to Knowledge → Quality
2. Select documents to analyze
3. Review scores and suggestions
4. Address issues identified

Quality Score Interpretation

Score	Status	Action
3.5-5.0	Good	Maintain or minor improvements
2.0-3.4	Medium	Revision needed
0-1.9	Poor	Major rewrite or remove

---

Improvement Techniques

Keyword Optimization

Include terms users actually search for:

Before:

Modifying Account Credentials

After:

How to Change or Reset Your Password

Also known as: modifying credentials, updating password, forgot password

Question-Answer Format

Structure documents as Q&A:

## Frequently Asked Questions

### How do I cancel my subscription?

To cancel your subscription:
1. Go to Billing → Subscriptions
2. Click "Cancel Subscription"
3. Confirm your cancellation

Your access continues until the billing period ends.

### Can I get a refund?

Refunds are available within 30 days of purchase. Contact [e-mail]
with your order number.

Chunking for Retrieval

Break large documents into logical sections:

Before: One 5,000-word document

After:

• Overview (500 words)
• Getting Started (800 words)
• Configuration (1,000 words)
• Advanced Usage (1,200 words)
• Troubleshooting (1,500 words)

---

Multi-Language Support

Translation Strategy

Approach	When to Use
Translate all	Global audience, resources available
Translate top 20%	Limited resources, prioritize impact
English only	Single-market focus

Translation Quality

• Use professional translation for critical content
• AI translation works for straightforward content
• Always have native speakers review

Managing Translations

Keep translations in sync:

1. Mark source language documents
2. Track translation status
3. Flag when source changes
4. Re-translate updated content

---

Source Management

Connector Configuration

For each external source:

Setting	Recommendation
Sync frequency	Daily minimum, hourly for fast-changing content
Include patterns	Specify exactly what to import
Exclude patterns	Filter out irrelevant sections
Archive policy	Remove deleted content after 7 days

Manual Sources

For content not in external systems:

1. Create dedicated manual source
2. Use consistent formatting
3. Include metadata (author, date)
4. Review quarterly

Source Prioritization

When documents overlap, set priority:

1. Primary: Official documentation
2. Secondary: FAQs and guides
3. Tertiary: Blog posts, announcements

---

Maintenance Schedule

Daily

• Review sync logs for errors
• Check for failed imports
• Monitor retrieval quality

Weekly

• Review low-quality score documents
• Update documents based on support tickets
• Check for duplicate content

Monthly

• Audit document accuracy
• Review analytics for coverage gaps
• Update seasonal/time-sensitive content

Quarterly

• Full knowledge base review
• Remove outdated content
• Assess translation needs
• Evaluate source effectiveness

---

Common Issues

Low Retrieval Quality

Symptoms: Agent gives irrelevant answers or says “I don’t know” when information exists.

Solutions:

1. Improve document titles
2. Add more keyword variations
3. Check embedding model configuration
4. Enable reranker
5. Review similarity thresholds

Duplicate/Conflicting Information

Symptoms: Agent provides inconsistent answers to the same question.

Solutions:

1. Consolidate duplicate documents
2. Set source priority
3. Remove outdated versions
4. Add canonical markers

Missing Coverage

Symptoms: Users ask questions with no matching documents.

Solutions:

1. Review “no answer” conversations
2. Analyze common escalation topics
3. Create content for gaps
4. Check connector include patterns

Slow Sync

Symptoms: Changes in source don’t appear in AGO.

Solutions:

1. Check sync schedule
2. Verify credentials
3. Review sync logs for errors
4. Consider more frequent sync

---

Analytics Usage

Coverage Analysis

Review which topics are covered:

Questions Answered:     75%
Questions Escalated:    15%
Questions Unknown:      10%

Focus on reducing “Unknown” by filling gaps.

Top Retrieval Misses

Documents frequently searched but not found:

1. Export retrieval analytics
2. Identify patterns in failed searches
3. Create or improve matching documents
4. Re-test with same queries

Document Usage

Which documents are most helpful:

Metric	Meaning
High retrieval + High resolution	Effective document
High retrieval + Low resolution	Needs improvement
Low retrieval	May need better keywords
Never retrieved	Consider removal

---

Content Governance

Change Management Workflow

Use Change Proposals to manage content changes systematically:

Best Practices:

Practice	Description
Review daily	Check pending proposals each day
Add notes	Always explain rejection reasons
Edit before accept	Refine proposed content when needed
Track sources	Use source_type to categorize proposals

Types of Proposals

Source Type	When to Use
quality_issue	From quality analysis (low scores)
feedback	From user-reported issues
manual	Staff-initiated improvements
ai_suggestion	Grammar fixes, AI recommendations

Knowledge Gap Tracking

Use Update Requests to track missing content:

1. Monitor gaps: Review pending requests regularly
2. Prioritize by volume: Multiple requests = critical gap
3. Link to conversations: Understand user context
4. Create content: Fill gaps with targeted documentation
5. Close the loop: Mark resolved with notes

Triage Strategy:

Priority	Criteria	Action
High	5+ requests on same topic	Create content immediately
Medium	2-4 requests	Schedule for next week
Low	Single request	Evaluate if content needed

---

Quick Wins

Immediate improvements you can make:

1. Fix titles - Make them question-based
2. Add FAQs - Top 10 support questions
3. Remove duplicates - Consolidate content
4. Update dates - Remove outdated info
5. Enable quality analysis - Find problem areas

---

Related

• Knowledge Overview — Feature overview
• Knowledge Quality — Quality analysis
• Set Up Your Knowledge Base — Setup tutorial