Write Docs That Teach Your AI When Rules Bend


TL;DR
Retiring a doc without leaving a structured stub means your AI agent keeps citing the dead article or goes silent. A short retirement notice — with a redirect reason, a replacement link, and an effective date — gives the agent something citable and keeps customers moving forward.
When you deprecate a feature or restructure your help center, the natural instinct is to unpublish the old article and move on. The problem is that your AI support agent indexed that article, and now one of two things happens: it cites a 404, or it hedges and tells the customer it doesn't know. Neither is acceptable when the answer actually exists — it just moved.
The fix isn't a redirect alone. Redirects help humans browsing your help center. They don't give an AI agent a citable piece of content that explains why the old path is gone and where the current answer lives.
A retirement notice is a short, permanent stub page that lives at the original URL (or as a named doc in your help center) and contains four things:
That last point matters more than it looks. Without a summary, the agent has to infer what the replacement article covers, and inference compounds over multiple hops.
Keep the whole thing under 150 words. Longer stubs get treated as full articles and confuse the agent about which piece of content is authoritative.
A concrete template:
[Original article title] — Retired [Date]
This article covered [feature/workflow]. As of [date], [what changed — one clause].
The current guide is [Article Title], which explains [one-sentence scope].
[Link: Article Title]
If you're on a plan created before [date], [edge-case note or link to legacy doc].
Fill every bracket. If you leave the edge-case line empty, delete it — blank placeholders are worse than omission.
Support agents handle customers on different plan vintages, different contract start dates, different migration states. A retirement notice without a date forces the AI agent to treat the change as universal and timeless. Add the date and the agent can say "this changed on [date] — if your account predates that, here's the legacy reference." That single sentence prevents a whole category of escalation.
Chattering indexes your help center docs and surfaces the most semantically relevant chunk when answering a question. A retirement notice competes with live articles for that slot. To make sure the notice wins when the question is about the deprecated topic — and that the agent follows the pointer to the replacement — do three things:
1. Keep the original title in the stub. The agent matches on the user's language. If a customer asks about "legacy billing settings," the stub with that phrase in the title will surface and hand off correctly.
2. Tag or categorize the stub distinctly. In Chattering's help center, you can add a custom label (we use retired-doc). That lets you audit which stubs exist and exclude them from "suggested articles" in the portal without removing them from the agent's index.
3. Don't redirect the stub URL. A permanent redirect means the stub page doesn't exist at that URL in the index — only the destination does. Keep the stub live and let the destination article carry its own canonical authority.
Make doc retirement a step in your feature-deprecation checklist, not an afterthought. When a product manager marks a feature deprecated, the support lead should own three artifacts: the new article, the retirement stub for the old one, and an internal note in the shared inbox pinning both for the team.
Say you're deprecating a custom CSV export in favor of a native integration. The old article "Exporting data via CSV" gets a stub. The stub points to "Syncing data with [Integration Name]." The inbox note tells the support team what to say if a customer is mid-migration. The agent gets a citable chain from old question to new answer without hallucinating a path that doesn't exist.
Open your help center and filter for articles last updated more than twelve months ago. Any article covering a feature that has since changed is a candidate for a retirement stub or an update. If your AI agent is citing it today, customers are getting stale answers. A thirty-minute audit and a handful of 100-word stubs will close that gap faster than any prompt engineering.
Keep the stub permanently. Deleting it removes the citable source and breaks any existing links customers may have bookmarked. A stub page is small and costs nothing to maintain.
Write the notice anyway, and point to the closest alternative or your roadmap page. Telling the agent 'this feature was removed and no equivalent exists yet' is a valid, citable answer — it prevents the agent from guessing.
Chattering will still surface the stub and cite it — which is the intended behavior. The stub's content guides the agent to the replacement; it doesn't suppress the answer, it redirects it.