Add: Use AI to improve support-ticket deflection with your docs

learn/ai-for-docs/ai-improve-support-ticket-deflection-docs.md

@@ -0,0 +1,63 @@
+---
+seo:
+ title: Use AI to improve support-ticket deflection with your docs
+ description: How to use AI to find the doc pages behind repeat support tickets, fix the real cause, and measure whether deflection improves.
+---
+
+# Use AI to improve support-ticket deflection with your docs
+
+Most support teams answer the same handful of questions every week, and most of those questions already have an answer somewhere in the docs. The problem usually is not missing content. It is content that nobody can find, trust, or apply at the moment they need it.
+
+That outcome has a name: "deflection," the share of developer questions resolved without a ticket. This article covers how to use AI to find the doc pages that generate tickets without anyone noticing, fix what is really wrong with them, and confirm the fix moved the number instead of just feeling better.
+
+## What deflection means for your docs
+
+Deflection sits alongside acquisition and adoption as one of three measurable outcomes for a documentation program, according to [key metrics for docs](https://redocly.com/blog/key-metrics-for-docs). Acquisition brings developers to your site, adoption gets them integrating, and deflection measures whether they can keep solving problems on their own once they are in production. When deflection works, a mature API program frees up support to handle harder problems instead of repeating the getting-started guide.
+
+Reduction in tickets tagged something like "can't find docs" is itself a trackable goal, tracked the same way you would track any product metric ([beyond anomaly detection](https://redocly.com/blog/beyond-anomaly-detection)). Effective deflection is not about avoiding support: it is about helping developers move faster and succeed without waiting on a reply. So a rising ticket count on a topic is not a support problem first. It is a docs signal.
+
+## Find the tickets your docs should already answer
+
+Start with the tickets themselves, not the docs. Export a sample of resolved tickets, including whatever doc link an agent eventually sent, and ask an AI model to cluster them by the underlying question rather than by product area or severity. A prompt like this works well as a starting point:
+
+```markdown
+You are reviewing 200 resolved support tickets for a REST API.
+Group them by the underlying developer question, not by the
+product area or ticket tag. For each cluster, list:
+1. The question in plain language
+2. How many tickets match it
+3. Which doc page (if any) an agent linked in the resolution
+4. Whether that page should have answered the question already
+```
+
+The clusters usually split into two kinds. Some point to a page that exists but fails, because it buries a prerequisite, uses a stale example, or answers a different question than the one developers meant to ask. Others point to nothing: no page addresses the workflow at all. Both are worth fixing, but they call for different work, so keep them in separate lists before you touch a single doc.
+
+## Turn ticket clusters into doc fixes
+
+When a page exists but underperforms, the fix is rarely "write more words." [Use AI to help developers find and understand your APIs faster](https://redocly.com/learn/ai-for-docs/ai-help-developers-find-understand-apis) makes the case for organizing pages around a single task, with prerequisites and errors on the same page as the operation they belong to, so a developer under deadline pressure does not have to piece an answer together from three tabs.
+
+Two causes are easy to miss because they live outside the words on the page itself. First, drift: when your live API changes and the docs do not, [use AI to detect drift between your docs and your live API](https://redocly.com/learn/ai-for-docs/ai-detect-drift-docs-live-api) shows up in support as a ticket that reads "your sample returns 404" rather than a docs complaint. Second, AI-readability: when an assistant pulls a confusing or outdated fragment and hands a developer a wrong answer with confidence, that also lands back in your queue, a pattern covered in [optimizations to make to your docs for LLMs](https://redocly.com/blog/optimizations-to-make-to-your-docs-for-llms).
+
+Small naming choices matter too. Unclear property names in a schema, like `usrNm` instead of `username`, lead to support tickets and frustrated developers on their own, independent of how well the surrounding paragraph reads ([use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews)). Run AI review on both the words and the schema behind them, because a ticket cluster about "the field names are confusing" is a review problem, not a writing problem.
+
+## Where AI assistants fit in the deflection loop
+
+At Redocly, we use an internal AI Assistant and MCP servers as a first line of support before a question ever reaches a subject-matter expert, answering routine questions about internal components and APIs directly ([how AI fits into modern API documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs)). That pattern deflects a real share of questions, but only when the assistant retrieves from pages that are current and well scoped.
+
+An assistant sitting in front of a wrong or outdated page does not remove a ticket. It just delays it and adds a wrong answer to the transcript before a human gets involved. Treat the assistant as a lever on top of good docs, not a replacement for fixing the page underneath it.
+
+## Measure whether deflection improved
+
+Before you credit an AI-assisted fix, set a baseline. Track ticket volume for the affected question for a few weeks before you ship anything, then compare the same window after. Useful signals include the reduction in support tickets per integration, the percentage of developer questions answered through docs or search instead of a ticket, and satisfaction scores on self-service flows ([key metrics for docs](https://redocly.com/blog/key-metrics-for-docs)).
+
+Watch time-to-first-successful-call as well, not just page views, since a page can get more traffic while still failing to get anyone unstuck. Re-test the same onboarding tasks after any navigation change, because a fix that helps one cluster can bury the page another cluster needed without anyone catching it right away ([use AI to help developers find and understand your APIs faster](https://redocly.com/learn/ai-for-docs/ai-help-developers-find-understand-apis)). When the number moves, publish it next to the docs roadmap. That is what turns deflection from a nice idea into a budget line your support team will keep funding.
+
+## Build a short list before you commit engineering time
+
+Not every cluster deserves the same response. Rank clusters by ticket volume and by how many production accounts they touch, then estimate the effort each fix needs: a rewritten paragraph, a moved section, or a new page entirely. A cluster with fifty tickets and a one-paragraph fix should ship before a cluster with five tickets and a rewrite that spans three pages, even if the second cluster feels more interesting to fix.
+
+Share the ranked list with support leads before you start writing. They usually know which questions repeat because a customer is confused, and which repeat because the underlying workflow genuinely has no good answer yet. That distinction changes whether AI should help you rewrite a page or flag a missing product capability for engineering instead.
+
+## How Redocly can help
+
+When ticket clusters point to a findability problem rather than a missing page, the fix depends on where developers look for answers first. [Revel](https://redocly.com/revel) is the external developer portal built for that kind of self-service discovery, with search and quickstarts positioned so partners and customers can resolve a question without filing one. Pairing that public surface with [Reef](https://redocly.com/reef) as an internal catalog keeps support and docs teams working from the same current source, so the fix you make after reading a ticket cluster reaches readers before the next round of tickets arrives.

learn/ai-for-docs/sidebars.yaml

@@ -30,6 +30,8 @@
   label: Use AI to build a searchable API catalog for your team
 - page: ai-help-developers-find-understand-apis.md
   label: Use AI to help developers find and understand your APIs faster
+- page: ai-improve-support-ticket-deflection-docs.md
+  label: Use AI to improve support-ticket deflection with your docs
 - page: ai-check-terminology-consistency-across-docs.md
   label: Use AI to check terminology consistency across your docs
 - page: ai-usability-testing.md