Add: Use AI to draft documentation PRs from your support tickets

learn/ai-for-docs/ai-draft-docs-prs-from-support-tickets.md

@@ -0,0 +1,90 @@
+---
+seo:
+ title: Use AI to draft documentation PRs from your support tickets
+ description: How to turn recurring support ticket patterns into an AI-drafted documentation pull request, then route it through Reunite review and Redocly CLI lint before merge.
+---
+
+# Use AI to draft documentation PRs from your support tickets
+
+Support queues fill up with the same handful of documentation complaints every month, and most of them never turn into a pull request. A ticket gets tagged, answered, and closed, while the page that caused the confusion stays exactly as it was.
+
+AI is well suited to that missing step. Feed it a cluster of related tickets, and it can draft the documentation change those tickets describe, so a reviewer gets a concrete pull request instead of another backlog line.
+
+This article covers building that pipeline: spotting a ticket pattern worth acting on, drafting the fix, and routing the result through the same review process your other documentation changes already use.
+
+## Why support tickets are an underused documentation signal
+
+Support tickets describe documentation problems in the reader's own words, which is more specific than most internal audits manage. A ticket that says "I can't tell if refresh tokens expire before or after the access token" names the exact confusion, on the exact page, in language a technical writer can act on directly.
+
+Most docs teams read tickets reactively: answer the question, close the ticket, move on. Few cluster tickets by the page or endpoint they reference, so the same confusing paragraph can generate ten near-identical questions before anyone notices the pattern. Clustering by page or workflow step over a rolling window, the last 90 days works well, turns scattered complaints into a short list of pages worth revising first.
+
+That list is the raw material for this workflow. Once you have a "ticket cluster," a set of tickets that trace back to one page or step, you have enough context for AI to draft a fix instead of only summarizing the complaint.
+
+## Turn a ticket cluster into a documentation brief
+
+Before drafting anything, translate the cluster into a brief the model can work from. Pull the ticket text, the page or section the tickets reference, and any agent notes about what finally resolved the confusion. Strip customer names and account details before pasting anything into a prompt.
+
+A workable brief includes four pieces: the page or section in question, three to five ticket excerpts trimmed to the confusing part, the correct answer as support currently gives it, and any limit on scope, for example "only touch the authentication page, not the whole quickstart."
+
+This step matters because a draft is only as good as what you paste in. A model reading ten tickets about token expiration with no confirmed answer attached will guess at the mechanics, which is exactly the invented detail this workflow needs to avoid. Give it the answer support agents already validated, and ask it to explain that answer clearly instead of rediscovering it.
+
+## How to prompt AI to draft the PR
+
+With the brief assembled, ask the model to draft the page edit itself, not a summary of the problem. A prompt that names the target section, the correct answer, and the tickets it should resolve produces a usable first draft:
+
+```markdown {% process=false %}
+You are drafting a documentation fix for [page or section].
+
+Tickets this should resolve (paraphrased, no customer details):
+1. [ticket excerpt]
+2. [ticket excerpt]
+3. [ticket excerpt]
+
+Correct answer, confirmed by support: [answer]
+
+Rules:
+- Edit only the section these tickets point to.
+- Do not invent details beyond the correct answer provided.
+- Match the existing heading style and terminology on the page.
+- Flag, instead of guessing, if the tickets contradict the current page text.
+
+Output: the revised section in Markdown, plus a one-line changelog entry describing the fix.
+```
+
+Ask for the changelog line in the same pass. That habit mirrors [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews), where a vague entry becomes a specific one that names the behavior it fixed, the same jump this workflow needs from a ticket-driven fix.
+
+Keep each prompt scoped to one cluster. A single prompt covering five unrelated pages produces a diff too large to review quickly, which defeats the point of drafting a pull request instead of filing another ticket.
+
+## What the draft gets right and what still needs a human
+
+AI handles the mechanical parts of this well: matching terminology, keeping heading levels consistent, and turning a paraphrased answer into full sentences a reader can follow. It also flags when a ticket cluster contradicts what the page currently says, often the real problem.
+
+A person still has to confirm the answer is current. Support agents give the correct answer for today's product behavior, but if the API changed since the last ticket came in, the draft will faithfully document something no longer true. Someone with product context needs to check that before merge, not after.
+
+The model also cannot judge tone for a sensitive topic, such as a workaround for a known limitation, without guidance on how directly to name that limitation. Give it that guidance in the brief, or expect to rewrite the paragraph that touches it.
+
+## Route the draft through your existing PR review
+
+Once the draft looks reasonable, open it as a real pull request instead of pasting it into a chat thread. Reunite connects documentation work to Git branches, commits, and pull requests, so a ticket-driven draft goes through the same path as any other content change. [Open a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/open-pull-request), and reviewers can compare the rendered before and after on the [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) review tab, not only the raw diff.
+
+Run Redocly CLI lint on the same branch when the fix touches anything the linter checks, such as terminology encoded as a rule or a broken example. [Redocly CLI built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) catch formatting and consistency problems a reviewer would otherwise spot by eye, and a ruleset built from your [API standards and governance](https://redocly.com/docs/cli/api-standards) policy keeps that check consistent across every pull request, not only the ones someone remembers to look at closely.
+
+[Review a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/review-pull-request) also closes a loop the ticket never could on its own: reviewers see which support conversations drove the change, so whoever approves the merge understands why the page needed to change, not only that it did. Link the ticket cluster in the pull request description; it doubles as a paper trail for the next content audit.
+
+## Best practices
+
+1. Cluster tickets by page or workflow step over a rolling window before drafting anything; one ticket rarely justifies a pull request on its own.
+2. Paste the support-confirmed answer into the prompt, and never let the model infer it from the tickets alone.
+3. Scope each prompt and each pull request to one cluster so reviewers can approve quickly.
+4. Ask for the changelog line in the same pass as the content fix, so the two never drift apart.
+5. Route every draft through the review path your documentation changes already use, so nothing ships without a human check on current accuracy.
+
+## What this approach cannot replace
+
+This workflow will not replace the support conversation that first surfaced the confusion, and it should not run unattended on tickets involving security, billing, or legal language. It turns a recognized pattern into a draft fast, but it does not decide which patterns are worth fixing, and it cannot confirm the product still behaves the way a ticket described months ago.
+
+Use it to shorten the distance between recognizing a recurring question and closing it for good, while keeping a person accountable for what the draft assumed.
+
+## How Redocly can help
+
+Turning ticket clusters into pull requests only pays off when the review step is fast and trustworthy. [Reunite](https://redocly.com/reunite) gives that draft a Git-backed home: open the pull request, invite reviewers, and let them compare the rendered before and after instead of a raw text diff. Pair it with [Redocly CLI](https://redocly.com/docs/cli/) so the same pull request runs lint rules built from your API standards and governance policy, catching formatting or terminology slips before a reviewer spends time on them. Together, Reunite and Redocly CLI turn a ticket-driven draft into a pull request your team can actually trust to merge.

learn/ai-for-docs/sidebars.yaml

@@ -16,6 +16,8 @@
   label: Use AI to review code examples for completeness and accuracy
 - page: ai-automate-documentation-reviews-pr-workflow.md
   label: Use AI to automate documentation reviews in your PR workflow
+- page: ai-draft-docs-prs-from-support-tickets.md
+  label: Use AI to draft documentation PRs from your support tickets
 - page: ai-review-docs-navigation-structure.md
   label: Use AI to review your docs navigation structure
 - page: ai-enforce-api-style-guide-at-scale.md