How to Measure Whether Your Documentation Works

Three or four numbers that say something real about your documentation, and a written note of what each one is lying about. The difficulty is structural: documentation succeeds when nothing happens. The ticket that never gets filed leaves no record anywhere, so everything below is a proxy standing in for an event you cannot observe.

Before you start

Get access to three things: page-level analytics for the help centre, the query log from your internal search, and support ticket volume broken down by topic. If you can only get one of the three, take the search log. It is the only source where the reader states, in their own words, what they came for.

You also need to know what else changed in the period you are about to measure. A launch, a pricing change, an outage or a seasonal dip will move every number here more than your writing does.

Steps

1. Write down what you expect to change, before you look at anything.
   Name the specific outcome: fewer tickets tagged billing, fewer repeat questions in the onboarding channel, faster time-to-first-integration. A metric chosen after the fact will always be the one that moved.

2. Record a baseline and the conditions around it.
   Capture four to eight weeks of the numbers you care about, and next to them write what was happening: headcount, releases, marketing spend, anything seasonal. The baseline without its context is worthless in six months when nobody remembers the quarter.

3. Measure at article level, never at site level.
   Site-wide totals move for reasons that have nothing to do with documentation quality. A single article, with a single topic and a single audience, is the smallest unit where a change is attributable to something you did.

4. Read the internal search log every week.
   Query volume, the zero-result rate, and the queries that returned results but got no click. This is the closest thing to a direct signal in the whole exercise, because the reader tells you what they wanted rather than you inferring it from where they clicked.

5. Instrument the handoff to support.
   Record the last help article viewed on your contact form, or add a required "did you find an article about this?" field. Without this you cannot tell a reader who was helped from one who read the page and gave up.

6. Pair every number with five real cases.
   For any metric that moved, read five actual tickets or five session recordings from that window. Numbers tell you something changed; the raw material tells you what. Teams that skip this step produce confident explanations that turn out to be wrong.

7. Publish the confounders alongside the figure.
   When you report the number, report what else could have caused it in the same sentence. This is not hedging. A metric presented without its alternative explanations gets treated as fact and then gets built on.

8. Re-measure on a fixed cadence, with the same window length.
   Monthly against the previous month, or quarter against quarter. Changing the window is the most common way a documentation programme accidentally proves its own success.

Only the third one fails to improve when users give up.

Common mistakes

Reading a fall in ticket volume as a win. Tickets fall when documentation gets better and when people stop believing support will help. Those are opposite outcomes with identical signatures. Before celebrating, check whether the contact link moved, whether response times slipped, and whether churn rose in the same period.

Treating correlation as causation because the timing fits. You rewrote the onboarding guide and activation improved. So did four other things that quarter. Unless you staged the change - shipping the new article to half your audience, or to one region first - you have a coincidence with a plausible story attached.

Using page views as a quality score. Heavy traffic on a troubleshooting article usually means the product is failing in that area more often, not that the article is excellent. Rising views on an error page is a product signal wearing documentation clothing.

Averaging across the whole help centre. A mean helpfulness score across ninety articles hides the eight that are actively wrong. Averages are the enemy of this particular problem, because the failures are concentrated and the successes are diffuse.

Measuring only what the tool reports by default. Analytics products ship with the metrics that are cheap to collect, not the ones that matter here. Time on page for a troubleshooting article is ambiguous in both directions - a long visit means thorough or lost, and nothing in the dashboard distinguishes them.

When this stops scaling

Reading raw material by hand is what makes any of this trustworthy, and reading is the part that runs out. One person can genuinely review a week of search queries and a sample of tickets for a help centre of perhaps thirty to fifty articles. Past that, the review becomes skimming, then becomes a dashboard nobody interrogates, and the proxies quietly get promoted to facts.

The other limit is structural rather than one of volume. Every metric here infers a reader's intent from their behaviour. The exception is the search box, where they type the intent directly - which is why the queries that returned nothing are worth more than any dashboard, and why a system that records them is worth more than one that reports averages. SupportPages keeps that list of unanswered questions per help centre. It will not tell you whether your documentation works either; nothing will. It will tell you what people asked it and did not get, which is the most actionable proxy available and still only a proxy.