Skip to main content
Documentation structure is a hypothesis. You believe readers will recognize a label, choose a section, and find the page that helps. Seeing what users do on your site tells you whether that hypothesis is right. No single metric captures documentation quality, so combine several signals and look for patterns.

​
Start with questions, not page views

High traffic can mean a page is valuable, confusing, or simply linked from the product. Low traffic can mean a page is unnecessary—or impossible to find. Begin with questions such as:
  • Can new users find the quickstart?
  • Do people search for a term your navigation doesn’t use?
  • Which tasks still generate support tickets after you document them?
  • Where do readers leave a multi-page procedure?
Choose signals that help answer a question rather than collecting numbers without a decision in mind.

​
Where to find the signals

Mintlify collects most of these signals for you on the analytics page:
  • Search shows what readers search for, which queries return no results, and how often readers click a result.
  • Feedback shows page ratings and written comments from readers, and feedback that AI agents submit.
  • User engagements includes a user flow chart that shows the paths readers take between pages and where they drop off, which answers “where do readers leave a multi-page procedure?”
  • Assistant groups the questions readers ask the AI assistant into categories and topics, with ratings for each answer.
The sections below cover what to look for in each.

​
Review search behavior

Search terms show readers’ language and intent. Look for:
  • Frequent queries with no useful result
  • Queries that use a different term from your docs
  • Repeated searches that become more specific
  • Searches for content that exists but ranks poorly
If readers search for “team permissions” while your docs say “workspace roles,” add the reader’s language to the page’s keywords frontmatter. Search matches keywords without showing them on the page, so readers find the right page while the product term stays consistent. If the mismatch is common, mention the reader’s term in the introduction too.

​
Connect support questions to content

Tag support tickets by task or topic. When the same question repeats, ask:
  1. Is the answer missing?
  2. Does it exist under a label readers won’t recognize?
  3. Is it on the right page but buried in the wrong section?
  4. Is the documentation accurate but the product workflow still confusing?
Documentation cannot fix every product problem. Treat repeated confusion as evidence, not automatically as a request for more prose.

​
Test real tasks

Give a colleague who doesn’t know the structure a realistic task. Ask them to think aloud while they find the answer using only the site. Watch where they look first, which labels they misunderstand, and when they backtrack. Don’t guide them. A five-minute task test often reveals more than a discussion among people who already know where everything lives. You can run a lighter version before you build anything: share only the navigation labels, with no content, and ask where they’d go for each task. Test the highest-value tasks first:
  • Reach a first successful result
  • Configure authentication
  • Recover from a common error
  • Find a specific reference value

​
Use assistant conversations carefully

Questions sent to the AI assistant are another source of user intent, often phrased in more detail than a search query. In assistant analytics, filter for topics that come up repeatedly and conversations users rated poorly. When readers ask questions that existing content should answer, the problem is usually structural: the information exists, but readers can’t find it or don’t recognize it as relevant. An assistant can sometimes compensate for poor navigation, so don’t treat a correct answer as proof that the underlying page is easy for humans to find.

​
Turn evidence into a small change

For each pattern, choose the smallest change likely to help:
  • Rename a heading or navigation group
  • Improve a page title or description
  • Add a missing cross-link
  • Split a mixed-topic page
  • Create a new page for a recurring task
  • Remove outdated content that competes with the right answer
Define what you expect to improve, make the change, and check the same signal again. Documentation gets better through small, testable iterations. Mintlify’s agent can draft some of these changes for you. The Fill gaps from assistant conversations and Improve docs from user feedback automations review those signals on a schedule and open pull requests with proposed fixes. You still decide which ones to merge. Next up: Keep docs accurate as your product grows—build the maintenance rhythm that keeps improvements from drifting out of date.