← Back to Blog

2026-08-25 • 6 min read • Measure

What the Questions People Ask Your Docs Can Tell You

When your documentation is connected to an AI client, every request carries the question, the passage that came back, and how well it matched. Here is how to read that and what to change because of it.

You can already see a lot about your documentation. Page views tell you which pages people open. Site search tells you what they type into your own search box. Feedback buttons and support conversations tell you where somebody got stuck badly enough to say so.

What none of that captures is the question somebody asked, failed to find an answer to, and quietly gave up on.

When your documentation is connected to an AI client as an MCP server, that question arrives as a request, and the request keeps its detail: the words the person used, the tool the client chose, the passage that came back, and how closely it matched. Over a few weeks those requests become something close to a transcript of what your documentation is being asked, sitting alongside your page views and support queue. This post is about reading them, with one example throughout.

Start with the shape of the traffic

Every server shows request volume, success rate, response time, requests over time, and a breakdown by tool, source and AI client, on the free tier. None of it says whether an answer was good. It says where to look, which is what a first pass is for.

Tool usage is the most informative of the free signals. Heavy use of find_api_reference means people are after exact endpoints and parameters. A jump in get_changelog after a release means version related work.

Source references show which of your sources is carrying the answers. Low volume is not automatically low value, because a source may serve a narrow but important workflow. Write down the questions you expect it to answer, then ask them.

Here is the example. Requests to a payments documentation server climb after a release, find_api_reference is the most called tool, and the API key rotation guide is cited more than any other page. That tells you where to look, not what anybody wanted.

Then read the questions in the words people used

The request log, included with Core analytics at $49 a month, shows the text of each question. This is where traffic turns into tasks, because people ask an AI client for what they are trying to do, not for the page they think it is on.

One question keeps arriving in different wordings:

How do I rotate this key without interrupting webhook delivery?

The constraint is the interesting part, not the topic. You knew people rotate keys. What you learn is that they are worried about webhooks while they do it, and that "without downtime" is a phrase your readers use.

Group what you see by repeated task, by repeated constraint, by vocabulary that differs from your headings, and by error messages pasted in verbatim. A cluster is worth acting on when it is frequent, the task matters, and your current answer is thin. One question is an anecdote.

Question text is other people's data, so apply the access and retention policy you would apply to a support transcript.

Look at the passage that came back

Action analytics, $99 a month with Core, shows the exact page, section and excerpt returned for each request, and how strongly it matched. This is the step that turns a guess about your content into a specific edit.

In the example, the rotation guide comes back every time, and the part that comes back is the numbered procedure. The webhook caveat sits two headings further down, under a heading about delivery retries. The source is right, the page is right, and what the reader receives is incomplete.

The fix is usually the smallest of these that works:

  • Move the caveat next to the procedure it applies to.
  • Give the section a heading in the words people typed.
  • Repeat a critical version or constraint where the task begins.
  • Put a complete example beside the explanation.

Confidence tells you how well your content matched the question, not whether the page is right. Read the excerpt, not the number. Code provenance ties a returned snippet back to the page it came from, so you can check its version and prerequisites.

The most valuable question is the one that came back with nothing

This is the reason to look at any of it.

When nothing in your content genuinely matches a question, the answer says so before it says anything else, and the AI client is told to pass that on rather than assemble something from whatever was nearest. That is useful to the person asking, and worth more to you, because it is a gap somebody just handed you, dated, counted, and worded in their own language.

Nobody files a ticket to say "your documentation does not mention this". They try, they find nothing, and they ask a colleague. Action analytics collects those questions into content gaps so you see them together rather than one at a time.

Before a gap becomes a backlog item, check that the question is in scope, that an answer does not already exist under different words, and that a clearer heading would not do the job. Then size it by how many requests it affects.

Make one change, then ask the same questions again

The way to know a change worked is to make one at a time against a fixed set of test questions.

  1. Observe. Review volume, tool usage, source references, and the question clusters that repeat.
  2. Investigate. Pick one cluster that matters, read the passages it returned, and establish what your documentation says today.
  3. Change. Make one focused edit: a clearer heading, a caveat moved next to the procedure, a complete example, or a new section.
  4. Compare. Ask your test questions again and see which passage comes back, from where, and how well it matched.

Record the date, the page, the questions you targeted, and the result. Volume is worth a weekly look; a trend needs enough repeated activity to compare against.

Read the slower signals as trends

Predictive analytics, $149 a month with Core and Action, adds the measures that only mean something over time. Requests to a working answer estimates how many requests it takes before somebody reaches something they can act on. Each source also gets an A to D grade for how efficiently it contributes to answers, which is a way to pick what to investigate rather than a verdict.

It also ranks the fixes it can see by how many requests they would affect, and shows a 30 day forecast. Treat both as planning estimates, and compare like with like: a quick lookup and an architecture question should not share a target.

What is free and what you pay for

What you see Plan
Volume, success rate, response time, requests over time, breakdown by tool, source and client Free
The text of each question, in a request log Core, $49/mo
Passage returned, page and section, excerpt, confidence, code provenance, content gaps, impact model Core + Action, $99/mo
Requests to a working answer, A to D source grades, ranked fixes, 30 day forecast Core + Action + Predictive, $149/mo

The first row comes with the free tier on every server you own. Per request detail is recorded whatever your plan, so a higher tier fills its views with history you already have, and new accounts get a 30 day trial with all analytics included.

The dashboard guide covers the views themselves, and you can build a server in the wizard to run this review against.

Keep going