How to measure documentation health: a four-part score from freshness, coverage, findability, and accuracy

Single-number doc metrics fail because they collapse different failure modes: a wiki can be fresh but full of holes, or complete but unfindable. Four parts keep the failure modes separate while still rolling up to one number leadership can track quarter over quarter.

The weights are deliberate. Freshness and coverage carry 60 of the 100 points because they are the cheapest to compute continuously and the earliest to decay. Findability and accuracy carry less weight but exist as tripwires: the no-component-at-zero rule means a wiki nobody can search or trust cannot pass on freshness alone.

Documentation health score (100 points)

Freshness    30   share of pages inside their review SLA
Coverage     30   share of catalog systems with the required set:
                  overview + runbook + architecture diagram
Findability  20   share of tracked doc searches ending in a click
Accuracy     20   share of sampled pages passing an owner spot check
                  (10 random pages per quarter)

Passing: 70 or more, with no component at zero.

For docs in a repository, git already stores everything: last commit date per file against the SLA for its doc class. For wiki-hosted docs, the platform API serves the same datum: the Confluence REST API returns version.when per page, and the Notion API returns last_edited_time on every page object. A script that walks either and buckets pages by age is an afternoon of work.

One honesty caveat: last-edited measures touch, not truth. A cosmetic edit refreshes the timestamp without verifying anything, and a page can be old and perfectly correct. Freshness is the cheap proxy; the accuracy component below is the correction. Both metric families get their own deep dives in documentation freshness metrics and documentation drift metrics.

# Share of git-tracked docs touched in the last 90 days
total=$(git ls-files docs | grep -c '\.md$')
fresh=$(git log --since='90 days ago' --name-only --pretty=format: -- docs \
        | grep '\.md$' | sort -u | wc -l)
echo "freshness: $fresh / $total"

Coverage needs a denominator, and the service catalog is the only honest one: every system the org runs, whether or not anyone wrote about it. Define a required set per system, a workable minimum is an overview page, a runbook, and an architecture diagram, then count systems that have all three. Counting pages without a denominator produces the classic vanity number where a wiki grows while coverage shrinks.

This metric surfaces the quiet failure of well-documented flagship services next to entirely undocumented internal ones, which is exactly the gap that hurts during incidents and onboarding.

Findability comes from search logs: the share of documentation searches that end in a click on a result. Most wiki platforms expose search analytics, and a zero-click search is a reader who asked and got nothing, which usually means the next stop was interrupting a colleague. Where search logs are thin, a task-based test with each onboarding cohort, find the runbook for service X, timed, is a serviceable substitute.

Accuracy is the component that cannot be scripted, so sample it: 10 random pages a quarter, each sent to its owner with one question, is every claim on this page still true. Track the pass rate. It is the most labor-intensive number of the four and also the one readers feel most directly, and the sampling design doubles as the audit described in the documentation audit checklist.

A healthy surface scores roughly: freshness 80 percent of pages inside SLA, coverage 90 percent of catalog systems with the required set, findability 70 percent of searches ending in a click, accuracy 9 of 10 sampled pages passing. That lands near 80 points. A score of 70 with no zero component is a defensible pass; below 50 usually means the right move is culling and regenerating rather than incremental fixing.

Run the score quarterly. More often and the accuracy sample becomes a burden; less often and the trend line is too sparse to steer by. The score also gives teeth to a docs freshness policy: the policy names the SLAs, the score reports compliance.

• Documentation freshness metrics
• Documentation drift metrics
• Documentation audit checklist
• A docs freshness policy template