Living Documentation: How Conversations Improve Your Knowledge Base
Traditional documentation gets stale the moment you publish it. But what if your documentation could learn from every conversation? Here's how we built self-improving knowledge bases.
The Documentation Problem
Every company has the same problem:
Week 1: Spend 40 hours writing comprehensive docs
Month 2: 20% of docs are already outdated
Month 6: Users stop trusting docs, ask support instead
Year 1: Docs are so stale you need to rewrite them
The cycle repeats.
Meanwhile, your support team answers the same questions hundreds of times. That knowledge never makes it back to the docs.
What If Documentation Could Learn?
Every conversation is a signal:
- What questions are users asking?
- What answers are they finding helpful?
- What's confusing?
- What's missing?
Living Documentation uses conversations to automatically:
1. Identify knowledge gaps
2. Suggest documentation improvements
3. Update docs based on actual usage
4. Route questions to the right content
How It Works
1. Question Detection
When users ask questions, we analyze them:
javascript
{
question: "How do I export my data?",
intent: "export_data",
entities: ["export", "data"],
sentiment: "neutral",
knowledgeBaseMatch: {
article: "data-export-guide",
confidence: 0.87,
section: "Exporting to CSV"
}
}
If confidence is high (>0.85), show the article.
If confidence is medium (0.50-0.85), ask clarifying questions.
If confidence is low (<0.50), escalate to human support.
2. Usage Tracking
Track how helpful each article is:
javascript
{
articleId: "data-export-guide",
metrics: {
shown: 342, // Times shown to users
helpful: 287, // Users clicked "This helped"
notHelpful: 23, // Users clicked "Not helpful"
bounced: 32, // Users left without reading
followUpQuestions: 18 // Users asked follow-up questions
},
helpfulness: 0.84 // (helpful - notHelpful) / shown
}
3. Gap Detection
Identify questions we can't answer:
javascript
// Questions with no good answer
{
question: "Can I bulk delete contacts?",
attempts: 47, // Times asked
confidence: 0.23, // Best match confidence
escalatedToHuman: 41, // Times sent to support
status: "missing_documentation"
}
This is gold. 47 people asked, we have no good answer. Time to write documentation.
4. Automatic Suggestions
The system generates documentation suggestions:
javascript
{
type: "missing_content",
topic: "bulk delete contacts",
evidence: {
userQuestions: [
"Can I bulk delete contacts?",
"How do I delete multiple contacts at once?",
"Is there a way to mass delete?"
],
frequency: 47,
supportTickets: 12,
suggestedTitle: "How to Bulk Delete Contacts"
},
priority: "high" // Based on frequency and user frustration
}
5. Content Improvement Recommendations
For existing content that's underperforming:
javascript
{
type: "improvement_needed",
article: "data-export-guide",
issues: [
{
type: "confusing_section",
section: "Export Formats",
evidence: "Users ask 'What format?' after reading",
suggestion: "Add comparison table of formats"
},
{
type: "outdated_screenshot",
evidence: "Interface changed in v2.0",
suggestion: "Update screenshots to match current UI"
},
{
type: "missing_use_case",
evidence: "15 users asked about exporting to Google Sheets",
suggestion: "Add section on Google Sheets integration"
}
]
}
Implementation
Step 1: Ingest Your Docs
javascript
// Upload documentation
await ilq.knowledge.upload({
source: 'notion', // or 'confluence', 'google-docs', 'markdown'
url: 'https://notion.so/your-docs'
});
// We automatically:
// - Extract text and structure
// - Generate embeddings for semantic search
// - Index for fast retrieval
// - Track versioning
Step 2: Enable Conversation Tracking
javascript
bot.onMessage(async (message, context) => {
// Search knowledge base
const results = await ilq.knowledge.search(message, {
appId: context.appId,
limit: 3,
minConfidence: 0.50
});
if (results.length > 0 && results[0].confidence > 0.85) {
// High confidence - show article
return {
content: results[0].summary,
source: results[0].article,
actions: [
{ label: 'This helped', action: 'feedback_positive' },
{ label: 'Not helpful', action: 'feedback_negative' }
]
};
} else {
// Low confidence - escalate
await ilq.analytics.trackGap({
question: message,
confidence: results[0]?.confidence || 0
});
return escalateToHuman(context);
}
});
Step 3: Review Suggestions
Every Monday, get a report:
Knowledge gaps found this week:
1. "Bulk delete contacts" - 47 questions, no good answer
2. "API rate limits" - 23 questions, existing doc has 0.42 confidence
3. "SSO setup with Okta" - 18 questions, no documentation
Content improvements needed:
1. "Data Export Guide" - Add Google Sheets instructions
2. "API Authentication" - Update for new OAuth flow
3. "Billing FAQ" - Add section on refunds
Step 4: Update Documentation
Two options:
Option A: Manual
Option B: AI-Assisted
javascript
// Generate draft from conversations
const draft = await ilq.knowledge.generateArticle({
topic: "Bulk delete contacts",
basedOn: conversationHistory,
style: "clear and concise"
});
// Returns:
// # How to Bulk Delete Contacts
//
// You can delete multiple contacts at once by...
// [Generated from actual user questions and support responses]
Review and publish the draft.
Real Results
Before Living Documentation
Company: B2B SaaS, 5,000 customers
After Living Documentation
6 months later:
ROI:
Advanced Features
Content Decay Detection
Identify documentation that's getting stale:
javascript
{
article: "API v1 Guide",
signals: [
"Traffic decreased 80% (users moved to v2)",
"Last updated 18 months ago",
"Users who land here ask 'Is this still relevant?'"
],
recommendation: "Archive and redirect to v2 documentation"
}
Personalized Documentation
Show different content based on user context:
javascript
// Beginner user asks "How do I export data?"
→ Show: "Getting Started with Data Export"
// Power user asks "How do I export data?"
→ Show: "Advanced Export Options and API"
Multi-language Support
Detect language, serve docs in user's language:
javascript
// User asks in Spanish: "¿Cómo exporto mis datos?"
→ Search Spanish knowledge base
→ If not found, translate English docs on the fly
→ Track gap: "Spanish docs needed for data export"
Proactive Documentation
Bot suggests docs before users ask:
javascript
// User navigates to Export screen
bot.send({
type: "suggestion",
content: "Need help exporting? Here's a quick guide:",
article: "data-export-guide"
});
Best Practices
1. Start With High-Volume Topics
Focus on questions asked most frequently. Don't try to document everything at once.
2. Keep Articles Focused
One article = one topic. Don't create 50-page guides. Create 50 one-page guides.
3. Use Real Language
Documentation should use the words users use, not internal jargon.
User: "How do I get my stuff out?"
Bad doc title: "Data Export Protocols"
Good doc title: "How to Export Your Data"
4. Update Frequently
Living documentation means frequent small updates, not infrequent major rewrites.
5. Celebrate Gaps
Knowledge gaps are opportunities, not failures. Each gap identified is a chance to help more users.
Getting Started
1. Connect your existing docs:
bash
ilq knowledge import --source notion --url https://your-docs
2. Enable conversation tracking:
javascript
ilq.analytics.enableKnowledgeTracking(true);
3. Review weekly reports:
4. Measure improvement:
The Future
We're working on:
Read our docs → | See how it works →
---
*Questions about Living Documentation? Email hello@ilq.ai*