| name | docs-as-code-metrics |
| description | Use when measuring or reporting documentation health — explains the four docs-health metrics (coverage, freshness, contribution, contract-sync) that docs-as-code:audit reports, how each is computed, what target to hold, and how to read a declining one. For setting a docs SLO or a weekly health review. |
Docs-as-Code Metrics
You cannot manage what you do not measure. docs-as-code:audit (via docs-coverage.sh) reports
four health metrics — this skill explains what each means, how it is computed, and what to do when
one trends down. Treat them as a docs SLO, reviewed weekly or before a release.
The four metrics
| Metric | What it measures | How it is computed | Hold at |
|---|
| coverage | % of docs with valid frontmatter (title + status) | share of docs that pass the frontmatter check | 100% — anything less means an unmanaged doc |
| freshness | active/published docs untouched too long | count of active/published docs with no git change in > 180 days | trend to 0 stale; investigate each |
| contribution | bus-factor signal | distinct doc authors in the last 90 days (from git) | ≥ 2 — one author = a bus-factor risk |
| contract-sync | code actually matches its contracts | result of check-contracts.sh (provider code ↔ contract) | green — a mismatch is a live breakage |
How to read them
- coverage < 100% — a doc has no
title/status; it is invisible to traceability and lifecycle.
Fix with docs-as-code:validate (it prints the exact file:line).
- freshness rising —
active docs are aging without edits. Either they drifted (the code moved
on) or they should be deprecated. Cross-check with docs-as-code:audit's drift view, then
docs-as-code:promote the dead ones to deprecated.
- contribution = 1 — one person holds the docs. Spread authorship deliberately; a single point
of failure for knowledge is the exact risk docs-as-code exists to remove.
- contract-sync red — the most urgent: a provider's code no longer matches its published
contract. A consumer is (or is about to be) broken. Fix the handler or version the contract.
Using them
Run docs-as-code:audit before a release and in the weekly review; the "worst metric trending
down" line tells you the single thing to fix. Set a team SLO (e.g. coverage 100%, freshness 0
stale, contribution ≥ 2, contract-sync green) and treat a miss like a failing test, not a nag.
Principle
A metric that no one acts on is vanity. These four are chosen to be actionable — each points at
a specific command (validate, promote, contract) that moves it. Report the number and the
next action.
