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