mintlify__docs/guides/improving-docs.mdx

---
title: "How to measure and improve documentation quality"
sidebarTitle: "Improve your docs"
description: "Use analytics, user feedback, and content audits to identify documentation gaps and improve the pages that matter most to your users."
keywords: ["documentation quality", "documentation metrics", "improve documentation", "content analytics", "documentation feedback"]
---

Good documentation is never finished. Products change, users' needs evolve, and content that worked six months ago may no longer reflect how the product behaves. Measuring documentation systematically helps you focus improvement efforts where they'll have the most impact, rather than guessing.

This guide covers how to use quantitative metrics, qualitative feedback, and business signals to find and fix the pages that matter most.

## Use quantitative metrics

Analytics give you a broad view of how documentation is performing. The most useful metrics are signals, not answers—they tell you where to look, not exactly what to fix.

### Page views and traffic

High-traffic pages are your most important documentation investment. Problems on a page with 10,000 monthly views affect far more users than the same problems on a page with 200 views.

Watch for:
- **Unexpected high traffic on error or troubleshooting pages.** Users shouldn't need to read about errors constantly. High traffic on these pages often signals a product UX problem worth reporting to your team.
- **Low traffic on pages you expect to be popular.** If a key getting started page has few views, users may not be finding it—check your navigation and internal links.

### Time on page

Long time on page can mean engagement or confusion. Short time can mean users found what they needed immediately or gave up and left.

Interpret time on page in context:
- Long reference pages should have shorter average time—users are scanning
- Tutorial content should have longer time—users are following steps
- If a simple how-to page has unusually high time, users may be struggling to complete the task

### Bounce rate

Bounce rate measures users who visit one page and leave without navigating further. A high bounce rate isn't inherently bad—users who find exactly what they need and return to their work represent a successful interaction.

Combine bounce rate with feedback scores to interpret it correctly. High bounce with low ratings signals failure. High bounce with high ratings signals success.

### Correlate traffic and satisfaction

Mintlify's analytics lets you see feedback scores alongside traffic data. Use this to prioritize:

- **High traffic, low satisfaction:** Popular pages with a poor user experience. Fix these first—they affect the most users.
- **Low traffic, high satisfaction:** Content that works but users aren't finding. Check whether navigation and internal links direct users there.
- **High traffic, high satisfaction:** Your best-performing pages. Review them for patterns to apply elsewhere.

## Collect qualitative feedback

Numbers tell you that something is wrong. Qualitative feedback tells you what.

### In-page ratings and comments

Enable feedback on your documentation pages so readers can signal when something isn't working. Open-ended comment fields surface specific issues—unclear steps, outdated screenshots, missing information—that ratings alone can't identify.

See [Feedback](/optimize/feedback) to configure feedback collection.

### Stakeholder input

Teams closest to users have information that analytics can't surface:

- **Support teams** know which documentation topics generate the most tickets and where users consistently get stuck
- **Customer success teams** see which pages new users struggle with during onboarding
- **Engineering teams** know when documentation describes behavior that's changed

Regular syncs with these teams—even monthly or quarterly—reveal gaps that user data alone misses.

### User research

Direct conversations with users provide depth that analytics and ratings can't. Ask users to walk through a specific task using only the documentation and narrate their thought process. Their instincts about where to look and where they get confused reveal structural and terminology problems that feel invisible to people who know the product well.

See [Understand your audience](/guides/understand-your-audience) for more on research methods.

## Align documentation with business goals

Documentation quality also shows up in business metrics. Connecting documentation work to business outcomes builds the case for documentation investment.

### Support efficiency

Track whether documentation improvements reduce support ticket volume for specific topics. When a how-to guide improves significantly, ticket volume for that topic should drop. This makes documentation ROI visible and measurable.

### User onboarding and activation

Documentation is often the critical path for new users activating the product. If onboarding analytics show users dropping off at a specific step, the documentation for that step is a likely cause.

### Retention signals

Documentation that's consistently inaccurate or incomplete erodes trust in the product, not just the docs. Users who encounter wrong documentation lose confidence in the reliability of the product itself. Documentation quality is part of product quality.

## Prioritize and act

Measuring is only useful if it drives action. A few frameworks for deciding what to fix first:

- **Fix high-traffic problems first.** The same hour of improvement work affects far more users on a page with 5,000 monthly views than a page with 50.
- **Respond to specific feedback.** When users leave specific comments—"this example doesn't work" or "this step is missing information"—those are high-precision signals that take little investigation to act on.
- **Focus on key user journeys.** Identify the three to five tasks that are most critical for your product's success and ensure the documentation supporting those tasks is excellent before worrying about the rest.

<Tip>
  Use [automations](/automations) to automate recurring improvements—like opening a pull request with suggested fixes for pages flagged by low feedback scores.
</Tip>

## Frequently asked questions

<AccordionGroup>
<Accordion title="How do I know which documentation pages to prioritize?">
Start with the intersection of high traffic and low satisfaction scores. These pages affect the most users and have the clearest signal that something isn't working. If you don't have feedback scores yet, start with your support team—they know which pages generate the most confusion without needing any analytics setup.
</Accordion>

<Accordion title="What's a good documentation satisfaction score?">
There's no universal benchmark. Track your own baseline over time and treat consistent improvement as the goal. A page rated positively by 80% of users is a reasonable target for important content. What matters more than the absolute score is the direction of the trend and how your most important pages compare to your average.
</Accordion>

<Accordion title="How often should I review documentation metrics?">
Monthly for high-traffic pages and overall satisfaction trends. Quarterly for a deeper content audit that looks at navigation patterns, search queries with no results, and pages without recent updates. Real-time review isn't necessary unless you've just shipped a major change.
</Accordion>

<Accordion title="What should I do if users give negative feedback but don't explain why?">
Look at the page analytically. High time on page combined with negative ratings often means users are struggling to follow instructions. Low time combined with negative ratings often means users didn't find what they were looking for. Cross-reference with support ticket topics for that page to get more specific signal. When you can't diagnose the problem from data, a short user interview session usually answers it quickly.
</Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Analytics overview" icon="chart-line" href="/optimize/analytics">
    View analytics and track documentation performance.
  </Card>
  <Card title="Feedback" icon="message-square" href="/optimize/feedback">
    Collect and analyze user feedback on your docs.
  </Card>
  <Card title="Understand your audience" icon="users" href="/guides/understand-your-audience">
    Research and define your documentation audience.
  </Card>
  <Card title="SEO" icon="search" href="/guides/seo">
    Optimize your documentation for search engines.
  </Card>
</CardGroup>