> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={null}
flowchart TD
    A[Product Documentation] --> B[Getting Started]
    A --> C[Features]
    A --> D[Troubleshooting]

    B --> B1[Quick Start Guide]
    B --> B2[Account Setup]
    B --> B3[First Steps]

    C --> C1[Feature A]
    C --> C2[Feature B]
    C1 --> C1a[Overview]
    C1 --> C1b[Configuration]
    C1 --> C1c[Troubleshooting]

    D --> D1[Common Issues]
    D --> D2[Error Messages]
```

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

```markdown theme={null}
## 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 support@example.com
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](../features/knowledge-change-proposals) to manage content changes systematically:

```mermaid theme={null}
flowchart LR
    A[Issue Identified] --> B[Create Proposal]
    B --> C[Review Changes]
    C -->|Approve| D[Apply Changes]
    C -->|Reject| E[Close with Notes]
    D --> F[Version Created]
```

**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](../features/knowledge-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](../features/knowledge-overview) — Feature overview
* [Knowledge Quality](../features/knowledge-quality) — Quality analysis
* [Set Up Your Knowledge Base](./knowledge-setup-tutorial) — Setup tutorial