Documentation freshness metrics: what to measure from git and wiki APIs, and which numbers predict rot

Age since last edit: days since anyone changed the page. Age since last review: days since a human explicitly attested the page is accurate, which is a different event, because a typo fix resets the first clock without touching the second. Edit-to-code-change ratio: over a window, edits to a doc divided by commits to the code it describes. View-to-edit ratio: how many reads the page gets per edit it receives, separating load-bearing pages from write-only ones. Broken internal link count: links on the page pointing at moved or deleted targets.

Everything else commonly proposed, word counts, page counts, contributor counts, measures volume, not freshness. Volume grows while a wiki rots.

The edit date is free: git and every wiki record it. The review date has to be created deliberately, because no system can infer that a human read the page and confirmed it against reality. In a repo, the convention is a last_reviewed field in front matter, updated only when someone actually verifies content. In Confluence, a page property or label serves the same role; in Notion, a dedicated date property on the database entry.

The distinction matters because the edit date lies in both directions. A page edited yesterday can be wrong, the edit was a formatting pass. A page untouched for two years can be right, the system it describes has not changed. The review date is the only one that means what readers hope the edit date means.

For repo-hosted docs, git log answers everything about edits. The per-file last edit is one command; the edit ratio is two counts over the same window; the stale list is a loop sorted by date. The broken link count comes from a link checker run rather than git itself, lychee or markdown-link-check in a scheduled job, counting failures on internal targets.

# Age since last edit for one page
git log -1 --format='%cs %h' -- docs/architecture.md

# Docs-to-code edit ratio over the last 90 days
docs=$(git log --since='90 days ago' --oneline -- docs/ | wc -l)
code=$(git log --since='90 days ago' --oneline -- services/ | wc -l)
echo "docs:$docs code:$code"

# Every doc not edited in a year, oldest first
git ls-files docs/ | while read -r f; do
  echo "$(git log -1 --format=%cs -- "$f") $f"
done | sort | awk -v cutoff="$(date -d '1 year ago' +%F)" '$1 < cutoff'

Confluence Cloud exposes the edit clock through its v2 REST API: GET /wiki/api/v2/pages/{id} returns the current version with its createdAt timestamp, and the versions endpoint gives the full edit history for computing edit frequency. View counts come from the analytics REST API on Confluence plans that include analytics, which is what makes the view-to-edit ratio computable there.

Notion returns last_edited_time on every page object retrieved through its API, so a script paginating a wiki database can build the full age distribution. What Notion's public API does not expose is view counts, so the view-to-edit ratio has to come from the in-product analytics rather than a script. Review dates exist in neither API by default; both need the explicit property convention from the previous section.

Review age and the edit-to-code-change ratio are the predictive pair. A page describing a service that took forty commits this quarter while the page took none is diverging almost by definition. Raw edit age alone is weak, because stable systems produce old-and-correct pages, and flagging those trains people to ignore the dashboard. Broken internal links are a lagging indicator but a strong one: they mean the pages around this one moved on and nobody maintaining this page noticed.

One scope note keeps the dashboard honest: freshness measures age and attention, not truth. Whether the content still matches the system is a different question with different measurements, covered in documentation drift metrics. A freshly reviewed page can still be wrong; freshness just makes it much less likely.

Numbers without thresholds decorate. The thresholds belong in a freshness policy, 90-day review for critical pages is a common anchor, and the enforcement belongs in a documentation SLA with a named owner per page. For architecture diagrams specifically, the cheapest way to keep the freshness numbers green is to make the update itself small: a diagram embedded by URL propagates an edit to every page showing it within minutes, and an agent connected to Datadef's MCP server can redraw it from the repo on request. Datadef does not watch the repo or detect changes itself; the metrics above are what tell you it is time to invoke it.

• Documentation drift metrics
• How to measure documentation health
• Docs freshness policy
• Documentation SLA