How to Measure Whether Your Documentation Is Working

Pageviews tell you almost nothing about documentation: a page everyone reads twice may be a page nobody understands. Here are the four signals that do predict whether the docs are working, and the monthly review that turns them into edits.

Documentation is working when readers find what they need and stop. That makes most web analytics actively misleading here: high pageviews can mean a page is popular or that it is confusing, and time on page can mean engagement or bafflement. The four signals that genuinely predict documentation quality are zero-result searches, support tickets whose answer already exists, task completion, and page-level feedback. Everything else is context.

None of the four is difficult to collect. What makes them useful is reviewing them on a schedule and converting each into a specific edit, which is the part that usually does not happen.

Why pageviews mislead

Consider two pages with identical traffic. One is the authentication guide, which every new user reads once and never returns to: high views, complete success. The other is a configuration reference that readers return to four times in a session because they cannot find the value they need: same number, total failure.

The metric cannot distinguish them, and neither can bounce rate: a reader who lands on a page from search, gets their answer in eight seconds and closes the tab is a bounce, and is also the best possible outcome.

In documentation, a short visit that ends the reader’s search is the goal. Most web metrics are built to treat it as a failure.

Four signals worth tracking

Zero-result searches

The clearest signal you have. Every query returning nothing is either a missing page or a missing synonym, and the list is short enough to read by hand each month.

Tickets already answered in the docs

Tag support tickets whose answer exists on a page the customer did not find. That count is a direct measure of discoverability rather than of coverage.

Task completion

Can a new user get through the quickstart unaided? Run it with five people twice a year. Five sessions surface more than a year of dashboards.

Page-level feedback

A rating widget on every page. The score is noise; the pattern across pages, and the free-text comments, are where the value is.

What each number actually tells you

Signal	What it means	How it misleads
Zero-result rate	Vocabulary or coverage gap.	Bots and empty submissions inflate it. Filter to queries of two or more characters with a real session behind them.
Search refinement rate	Readers searching twice in a row did not get it the first time.	Some refinement is normal exploration. Watch the trend rather than the level.
Exit rate on a task page	On a step-by-step page, a high exit part-way through means people gave up.	On a reference page, exiting is success. Never compare the two.
Ticket deflection	Docs are absorbing questions before they reach support.	Falls when the product gets simpler as well as when the docs get better.
Helpfulness rating	Direction of travel on a specific page.	Heavily skewed to people who are annoyed. Read the comments, not the average.
Time to first successful call	The single best number for developer docs.	Needs product instrumentation, not analytics. Worth the effort anyway.

Never set a target on a documentation metric

The moment “raise the helpfulness score” becomes a goal, the widget moves to the bottom of the page and the prompt gets friendlier. Use these numbers to decide what to look at next, not to report progress upwards. A metric that is being reported on stops being a measurement.

The qualitative half, which is most of the value

Numbers tell you where to look. They cannot tell you what is wrong with a page, and four cheap habits will.

Read the raw search log. Twenty minutes with the actual strings people typed beats any dashboard. You will find terminology you do not use, features people expect you to have, and error messages you never documented.
Watch someone use the docs. Once a quarter, silently. Every question they ask aloud is a missing sentence.
Read the support queue yourself. The tickets, not a summary of them. The wording customers use is the wording your pages should be findable by.
Ask new hires what confused them, in week two. They are the only people who will ever see your documentation with fresh eyes, and the window closes fast.

A monthly review that produces edits

The point of measurement is a changed page. An hour a month is enough if it ends in a list of specific edits rather than a report.

Pull the zero-result queries. Sort by frequency. Each one becomes either a synonym entry or a page on the backlog, so decide which, then and there.
Pull the tickets tagged “answered in docs”. For each, open the page that answers it and ask why it was not found. Usually the answer is a heading that does not use the customer’s words.
Read every free-text comment from the rating widget. Most are useless. The ones that are not are worth the whole exercise.
Check the top ten pages for staleness. High traffic and an old last-modified date is the highest-risk combination you have.
Write down three edits and do them. Not a plan: three edits, this month. A review that produces a document instead of a diff has failed.

Track the last-reviewed date, not just last-modified

A page edited last week for a typo looks fresh and may still be wrong. A separate “last verified against the product” date, updated only when someone actually checked, is a far better staleness signal, and it makes the review queue obvious.

Common questions

What is a good helpfulness score?

There is no meaningful benchmark, because the score depends far more on where the widget sits and how the question is worded than on the page. Compare a page against its own past, and compare pages against each other within your own site. Comparing against anyone else’s number is meaningless.

Should we A/B test documentation?

Rarely worth it. Documentation traffic is usually too small for significance on anything but the highest-traffic pages, the effect you care about happens off-site in the reader’s terminal, and the variance across query intent swamps the variance across wording. Spend the same effort watching five people use the page instead.

How do we measure documentation that is mostly read by AI assistants?

Indirectly, for now. Watch referral traffic from assistant surfaces where it is attributed, and watch support tickets that quote your documentation back at you incorrectly. That is the clearest sign a page is being retrieved and misread. Structuring pages so a chunk stands alone helps both machines and humans; see Writing Documentation That AI Assistants Cite Correctly.

Who should own these numbers?

Whoever writes the documentation. Handing documentation metrics to a separate analytics function produces reports rather than edits, and the loop between noticing a gap and fixing a page should be short enough to close in an afternoon.

Feedback on every page

Doku ships a per-page star rating stored with the post, so the feedback signal is available without a third-party script. See Features.