How to measure and improve documentation quality

Documentation is never finished. The product moves, readers’ needs change, and a page that was right six months ago quietly stops being right. Measuring your docs systematically tells you where to spend the next hour of work, instead of fixing whatever happens to annoy the team this week.

This guide covers three kinds of signal — numbers, reader feedback, and business outcomes — and how to turn them into a ranked list of fixes. It is also explicit about which of those signals Reed collects. The short answer is: none of them directly. Reed builds a static site. Measurement is something you add, and this page tells you where.

What Reed gives you to measure with

Reed emits no tracking of its own and runs no server that could log requests. What it does provide is a way to add an analytics provider by configuration:

json

{
  "analytics": {
    "provider": "plausible",
    "options": { "domain": "docs.example.com" }
  }
}

analytics is a closed registry, not a place to paste a snippet. The supported providers are ga4, plausible, posthog, fathom, umami and matomo, and each identifier is validated at reed check, so a malformed id fails before you ship a site that silently records nothing. If your provider is not on the list, it is not configurable today. See Analytics.

Everything in the next section — page views, time on page, bounce rate — comes from that provider’s dashboard, not from Reed.

Your host is a second source. Most static hosts and CDNs report request counts and 404s per path. A steady stream of 404s on one old URL is a missing redirect, and those are cheap to fix.

Use quantitative metrics

Numbers are signals, not answers. They tell you where to look, not what is wrong.

Page views

Your highest-traffic pages are your biggest investment. A flaw on a page with 10,000 monthly views costs fifty times more than the same flaw on a page with 200.

Watch for two patterns:

• Troubleshooting and error pages with high traffic. Readers should not need an error page constantly. Sustained traffic there usually points at a product problem, not a docs problem. Report it to the team that owns the feature.
• Key pages with low traffic. If your quickstart gets few views, readers are not finding it. Check the navigation and the internal links that should lead there. Navigation and Linking cover both.

Time on page

Long time on page can mean engagement or confusion. Short time can mean the reader got the answer instantly, or gave up. Read it against the page type:

• Reference pages should be short visits. Readers scan for one value and leave.
• Tutorials should be long visits. Readers are following steps.
• A simple how-to with unusually long visits suggests readers are struggling to finish the task.

Bounce rate

A bounce is a visit to one page with no further navigation. On docs that is often success: the reader found the one thing they needed and went back to work.

Bounce rate means nothing on its own. Pair it with a satisfaction signal. High bounce with positive feedback is a page doing its job. High bounce with complaints is a page failing.

Search queries

Search on a Reed site runs entirely in the reader’s browser, against an index shipped with the site. Nothing is sent to a server, so there is no search log to read, and “searches with no results” is not a report you can pull.

Reed cannot emit custom analytics events either — each supported provider gets only its page-view snippet — so you cannot add that signal yourself. Treat it as unavailable and lean harder on support tickets, which carry much of the same information: they are, in effect, the searches that failed.

Correlate traffic with satisfaction

The most useful view puts traffic next to a satisfaction signal:

Traffic	Satisfaction	What to do
High	Low	Fix first. Popular pages with a bad experience hurt the most readers.
Low	High	The page works but readers are not finding it. Fix navigation and inbound links.
High	High	Your best pages. Study them for patterns worth copying.

Reed does not put these two numbers side by side for you. Traffic comes from your analytics provider. Satisfaction comes from the feedback channels below. Joining them is a spreadsheet exercise, and it is worth doing once a quarter.

Collect qualitative feedback

Numbers tell you something is wrong. Readers tell you what.

Give readers a way to report problems

Nothing on a Reed page collects a rating or a comment. Every page’s footer does show a static “Was this page helpful?” prompt, but it submits and stores nothing — readers will see it, so do not count on it, and give them a channel that works. That channel is yours to choose, and the simplest one is usually the best.

• An issue link. If your docs live in a public repository, point readers at its issue tracker. Add a “Report a problem” link to footer.columns in docs.json and it appears on every page:

json

{
  "footer": {
    "columns": [
      {
        "label": "Feedback",
        "links": [
          { "label": "Report a problem", "url": "https://github.com/acme/docs/issues/new" }
        ]
      }
    ]
  }
}

• A form or private tracker, in the same place, for private docs or readers without an account on your git host. Footer links must be http(s) or root-relative URLs — a mailto: link is rejected — so point at a web form or a support portal rather than an address.

A rating count is not something you can get from the site itself: the footer prompt stores nothing, and Reed cannot emit custom analytics events.

Written comments are worth more than ratings. “This example fails on step 3” takes five minutes to act on. A thumbs-down takes an investigation.

Talk to the people closest to readers

Some teams know things no analytics dashboard will show you:

• Support knows which topics generate the most tickets and where readers get stuck.
• Customer success sees which pages new customers struggle with during onboarding.
• Engineering knows when a page describes behavior that has since changed.

A short monthly or quarterly sync with each surfaces gaps the data misses.

Watch real readers use the docs

Ask a user to complete one real task using only the documentation, and to think out loud while they do it. Where they look first, what word they search for, where they hesitate — these reveal structural and terminology problems that are invisible to anyone who already knows the product. Understand your audience covers research methods in more depth.

Tie documentation to business goals

Documentation quality shows up in numbers the rest of the business already tracks. Connecting to them is how you make the case for spending time on docs.

• Support volume. When you rewrite the page behind a common ticket topic, tickets on that topic should fall. Track it. That is documentation ROI, measured.
• Onboarding and activation. Docs are often the critical path for a new user. If product analytics show people dropping off at one setup step, the page for that step is a prime suspect.
• Retention and trust. Readers who hit wrong instructions do not just distrust the docs. They start to distrust the product. Documentation quality is part of product quality.

Discovery beyond your own site

Some readers never visit your site at all; they ask a search engine or an AI assistant. Two external checks are worth a regular look:

• Search Console (or your search engine’s equivalent) shows which queries lead to your pages and which pages are not indexed. Set site in docs.json so Reed emits a sitemap to submit. See SEO.
• AI answers. Ask the assistants your readers use the questions your docs answer, and see whether your pages are cited and whether the answers are right. Every Reed build emits llms.txt and per-page markdown mirrors to make that more likely. See GEO.

Prioritize and act

Measurement is only worth the effort if it changes what you work on next.

• Fix high-traffic problems first. An hour of work on a page with 5,000 monthly views reaches a hundred times more readers than the same hour on a page with 50.
• Act on specific feedback fast. “This command is wrong” is a precise signal with an obvious fix. Clear these first; they are the cheapest wins you will get.
• Protect the critical journeys. Name the three to five tasks that matter most for your product’s success. Make the docs behind those excellent before polishing anything else.

Reed has no automation that opens fix pull requests for you. The loop is manual: pick a page from the list, fix it on a branch, merge it. See Git workflows.

Frequently asked questions

Which pages should I fix first?

Start where high traffic meets low satisfaction. Those pages affect the most readers and carry the clearest signal that something is broken. If you have no satisfaction data yet, ask your support team. They know which pages cause confusion without any analytics at all.

What is a good satisfaction score?

There is no universal benchmark. Establish your own baseline and aim to improve on it. A page that most readers rate positively is a reasonable target for important content, but the trend matters more than the absolute number, and so does how your key pages compare with your average.

How often should I review metrics?

Monthly for high-traffic pages and overall trends. Quarterly for a deeper audit of navigation paths, support ticket topics, and pages that have not changed in a long time. Watching in real time is only useful right after a major release.

Readers say a page is bad but not why. What now?

Read the page against its numbers. Long visits plus complaints usually mean readers are struggling to follow the steps. Short visits plus complaints usually mean they did not find what they came for. Cross-reference support tickets on the same topic. If the data still does not explain it, one short session watching a user try the task almost always will.