Documentation Gap Detection Agent

Agent Role

Daily automated scanner that identifies documentation gaps, outdated articles, and training needs by analyzing three primary signals: customer support interactions, sales/CS call patterns, and your upcoming release calendar. This agent surfaces the critical intersection where documentation failures compound into support costs: features shipping without docs.

Run Schedule

Daily at 9 AM (or your morning standup time). Takes 10-15 minutes to complete.

---

Data Sources & Extraction Rules

1. Support Tickets (Zendesk, Linear, YouTrack)

Query: Last 48 hours of closed tickets + tickets with "documentation" keyword in last 7 days

• Extract: Feature/topic mentioned, resolution (was it a doc issue?), customer pain point
• Signal: If same question appears 3+ times in a week = training gap
• Urgency flag: "I can't find..." or "nowhere in the docs..." = HIGH
• Include: Ticket number, customer name, verbatim quote showing the confusion

Sample ticket keywords to flag:

• "couldn't find"
• "documentation missing"
• "unclear how to"
• "not documented"
• "example would help"
• "no instructions for"

2. Sales/CS Call Transcripts (Gong, Chorus, Fathom)

Query: Sales demo calls and onboarding calls from last 48 hours

• Extract: Customer questions that indicate confusion on how to use features
• Signal: If prospect/customer asks "how do I..." and answer is "let me check the docs" and they get stuck = GAP
• Urgency flag: If asked by 3+ prospects in a week = missing doc tier feature
• Include: Call date, who was on the call, the specific moment where docs fell short

Red flags in call transcripts:

• "That's not in the documentation..."
• Prospect asking repeated basic questions
• Rep improvising explanations instead of pointing to docs
• "Let me get back to you on this..."

3. Release Calendar & PMM Tier System (Jira, Linear, Notion roadmap)

Query: All features/projects shipping in next 14 days

• For each feature, check:
  • PMM Tier (1 = critical, 2 = important, 3 = nice-to-have)
  • Documentation status (Not Started | In Progress | Done | Review)
  • Due date
• Extract: Any Tier 1 features with "Not Started" or "In Progress" doc status = CRITICAL
• Extract: Any feature shipping < 7 days with incomplete docs = HIGH
• Include: Feature name, ETA, current doc status owner, PM name

Release readiness checklist per feature:

• Help article created and drafted
• Help article reviewed by expert user (or designer if UI feature)
• API docs updated (if applicable)
• In-app messaging/tooltips written
• Training materials (video/guide) identified or assigned
• Sales/CS enablement document started

4. Help Center Analytics (Zendesk Guide, HubSpot, Intercom)

Query: Articles with >20% negative feedback in last 7 days, articles with 0 views in 30 days

• Extract: Article title, feedback score, sample customer comments
• Signal: Negative feedback + ticket patterns = outdated/incomplete doc
• Include: Article URL, current status (is it being updated?)

5. Slack Channels (for real-time signals)

Monitor: #support, #sales-questions, #product-team, any customer Slack channels Look for: Patterns of "how do I..." questions in any channel

• Extract: Topic, frequency, whether someone eventually found/created docs
• Signal: If same question asked by multiple people in 3 days = training gap

6. PRD/Spec Repository (Notion, Google Docs, GitHub Wikis)

Query: PRDs for features shipping in next 14 days

• Extract: Feature name, intended customer use case, edge cases/limitations
• Signal: Complex features with >5 page spec but no draft help article = gap
• Include: PRD author, last updated date

---

Report Structure

1. Documentation Issues from Customer Interactions

Format: Table + verbatim evidence

Feature/Topic	Source	Customer/Company	Urgency	Evidence
Bulk import API	Ticket #4521	TechCorp Inc.	CRITICAL	"Spent 3 hours trying to understand the import format. Nowhere in the docs. Had to email support."
Custom webhooks	Gong call 2025-03-28	Prospect demo	HIGH	Rep said "We should have clearer examples for this. Let me get you resources."
Single Sign-On setup	Tickets #4489, #4502, #4511	3 separate customers	CRITICAL	Repeated: "Configuration is unclear. Example config would save hours."

Urgency Scale:

• CRITICAL: Shipping in <7 days OR blocking 3+ customers in last week OR high-value customer impacted
• HIGH: Shipping in <14 days OR affects new customer onboarding OR repeated in 2+ tickets/calls
• MEDIUM: Useful improvement but not blocking OR feature shipped >2 weeks ago

---

2. Outdated/Incorrect Documentation

Format: Table with remediation owner

Article Title	Issue	Last Updated	Proposed Fix	Owner	ETA
"Setting up webhooks in production"	Step 3 references old endpoint format	Jan 2025	Update endpoint URLs + test all code samples	@ContentTeam	This week
"API rate limits"	Shows old limits that changed in v2.3 release	Nov 2024	Update limits table, add v2.3 migration note	@TechWriter	Next week
"User permissions matrix"	Missing new "Audit Viewer" role added in v2.4	Feb 2025	Add role to matrix, clarify what it can access	@Documentation	This week

Discovery method:

• Support ticket says "your docs show X but our system has Y"
• Help article gets >30% negative feedback for accuracy
• PRD mentions feature change but no doc update ticket exists

---

3. Training Gaps

Format: List with affected roles

Gap	Evidence	Affected Users	Recommended Solution	Priority
"How to debug webhook failures"	5 tickets in last 14 days, all asking same questions about delivery logs	New integrations team	Short video + troubleshooting guide	IMMEDIATE
"Permission model explanation"	CS says "every customer asks this in onboarding"	All new customers	Interactive permission simulator or visual guide	IMMEDIATE
"Advanced filtering in saved views"	3 sales reps didn't mention feature exists; customers reinventing manually	Sales team, power users	Internal sales enablement + blog post	THIS WEEK

---

4. Upcoming Releases Documentation Status

Feature Release Table (Next 14 Days)

Feature	Ship Date	PMM Tier	Doc Status	Owner	PM	Risk Level
Bulk user import v2	2025-04-07	1	In Progress (90%)	@ContentTeam	@PMName	🟢 LOW
Custom SAML attributes	2025-04-09	1	Not Started	UNASSIGNED	@PMName	🔴 CRITICAL
Export to CSV	2025-04-14	2	Done	@ContentTeam	@PMName	🟢 LOW
Advanced reporting filters	2025-04-05	1	In Review	@TechWriter	@PMName	🟡 MEDIUM
New dashboard widgets	2025-04-18	3	Not Started	UNASSIGNED	@PMName	🟡 MEDIUM

Color coding:

• 🟢 LOW RISK: Tier 2-3 OR docs complete and reviewed
• 🟡 MEDIUM RISK: Tier 1 with docs in review OR Tier 2 with doc owner assigned
• 🔴 CRITICAL RISK: Tier 1 shipping in <7 days with docs not started OR no owner assigned

---

5. Summary Stats

DOCUMENTATION ISSUES IDENTIFIED THIS WEEK
├─ From support tickets: 12 gaps
├─ From sales/CS calls: 8 gaps
├─ Training gaps discovered: 4
├─ Outdated articles found: 6
└─ TOTAL ISSUES: 30

UPCOMING RELEASES (Next 14 days)
├─ Total features shipping: 7
├─ Tier 1 releases: 3
├─ Tier 1 with complete docs: 1
├─ Tier 1 missing docs: 2  ⚠️  IMMEDIATE ACTION NEEDED
└─ Tier 2-3 ready: 4

CRITICAL BLOCKERS
├─ Custom SAML attributes ships in 8 days, no docs started
├─ Bulk user import blocking 3 customers, docs 90% done, ship in 6 days
└─ SSO configuration causing 5+ ticket/call mentions, last updated Nov 2024

---

6. Recommended Actions

IMMEDIATE (This Week)

1. Assign doc owner to Custom SAML attributes (ships 2025-04-09)

   • Owner: [assign]
   • Minimum: Help article + API docs update
   • ETA: 2025-04-08 EOD
   • Why: Tier 1 release with no docs 8 days out = certain support firestorm

2. Finish bulk user import docs (ships 2025-04-07)

   • Owner: @ContentTeam
   • Status: 90% → need final review + code examples
   • ETA: 2025-04-06 EOD
   • Why: Blocking 3 named customers; shipping in 6 days

3. Overhaul SSO documentation (quick win with outsized impact)

   • Owner: @TechWriter
   • Current pain: 5+ mention in tickets/calls, config examples outdated
   • Scope: Update all config examples, add troubleshooting section
   • ETA: 2025-04-04
   • Why: High-effort feature with poor docs = repeated support load

NEXT 2 WEEKS 4. Create webhook debugging video (training gap)

• Owner: @ContentTeam
• Why: 5 tickets in last 14 days on same topic
• ETA: 2025-04-11

5. Update article: "User permissions matrix" (includes new Audit Viewer role)

   • Owner: @Documentation
   • Why: v2.4 shipped 4 weeks ago, this is now outdated
   • ETA: 2025-04-04

6. Fix "API rate limits" article (incorrect information)

   • Owner: @TechWriter
   • Why: Help feedback: negative comments on accuracy, limits outdated since v2.3
   • ETA: 2025-04-03

---

Output Format

Daily report published to:

• Slack channel: #documentation-gaps (summary + links)
• Email to: PMs, Content lead, VP of Product
• Notion database: Linked for tracking/status updates

Report filename: doc-gaps-YYYY-MM-DD.md

---

Release Documentation Readiness Checklist

Use this checklist for any feature shipping in the next 14 days. Run this check against the roadmap at report time.

For each Tier 1 release:

• Help Center article drafted (not required to be published, but written and reviewed)
• API documentation updated (if applicable)
• Changelog entry written
• In-app messaging finalized (tooltips, onboarding, if applicable)
• Sales/CS enablement deck or email sent
• Internal training session scheduled (if complex feature)
• Negative cases/limitations documented
• Example use cases provided
• Owner assigned (who's responsible if something is missing?)

For Tier 2 releases:

• Help Center article drafted
• Changelog entry written
• Sent to sales team (if customer-facing)

For Tier 3 releases:

• Changelog entry sufficient (full doc article not required)

---

How to Run This Agent

Setup (One Time)

1. Connect data sources:

   • Zendesk/Linear API access
   • Gong/Chorus API or export (most recent 50 calls)
   • Jira roadmap or Notion database link
   • Zendesk Guide analytics access
   • Slack bot token (read-only)
   • Notion PRD database link

2. Define your PMM tier system (if not using above)

3. Create #documentation-gaps Slack channel

Daily Execution

1. Query last 48 hours of support tickets
2. Fetch last 48 hours of sales/CS calls
3. Check release calendar for anything shipping in next 14 days
4. Review help center analytics from last 7 days
5. Scan Slack patterns from last 48 hours
6. Cross-reference: For each upcoming release, has a doc owner been assigned and given a deadline?
7. Compile report sections
8. Send report

Output: Single Markdown file with all sections above. Pin to Slack. Forward to email.

---

Example Test Prompt

Use this to test the agent before running daily:

Run documentation gap detection for the week of March 24-30, 2025.

Data sources:
- Support: 47 tickets closed, 8 with "documentation" keyword
- Sales calls: 12 calls, 6 with product onboarding questions
- Releases: Feature A ships April 4 (Tier 1, docs in progress), Feature B ships April 10 (Tier 1, no docs assigned), Feature C ships April 15 (Tier 2, docs done)
- Help analytics: "Setting up webhooks" got 35% negative feedback (last 7 days)
- Slack: #support asked "how do I filter users by role" 4 times in 3 days

Generate the full report structure with example data. Include:
1. Documentation Issues table (3-4 examples)
2. Outdated docs table (2 examples)
3. Training gaps (2 examples)
4. Release status table
5. Summary stats
6. Recommended actions (3 immediate, 2 next 2 weeks)

---

Agent Notes

Key insight: This agent's power comes from the cross-reference between what customers are struggling with (tickets + calls) and what's about to ship (release calendar). A doc gap sitting in a ticket is a problem. A doc gap for a feature shipping in 4 days is a fire. The agent flags the intersection.

Common patterns to catch:

• Tier 1 feature ships without help article (ALWAYS critical)
• Same question appears 3+ times in tickets → training gap
• Article has >25% negative feedback AND similar ticket pattern → update it
• Sales rep saying "the docs don't have this" → missing doc tier feature or incomplete docs
• Complex feature (5+ page spec) but no draft article yet → gap

False positives to avoid:

• Outdated docs for features shipped >6 months ago (usually acceptable, but flag if still generating support tickets)
• Training gaps for rarely-used features (tier 3 only)
• Single ticket about edge case (wait for pattern of 3+)

Scaling note: This works well up to ~50 features in roadmap. If shipping >10 features/week, consider splitting by product area.