What is documentation freshness, and how do you measure it in Metabase?
Documentation freshness is the share of active content reviewed or meaningfully updated inside an agreed window. It finds operational docs that may no longer match how the work actually runs.
TL;DR — Freshness = active content reviewed inside its policy window ÷ active content. Use review dates where possible; an automated edit is not proof of review.
Definition
Documentation freshness = current, active items reviewed within the required window divided by all active items in scope. Use different windows for policies, runbooks, project docs, templates, and archives.
Data needed
- Stable content ID, content type, and container or workspace
last_reviewed_at, or a meaningfulupdated_atfallback- Owner, reviewer, lifecycle status, and archived/deleted flags
- A freshness-policy window by content class
SQL pattern
Documentation freshness by content typePostgreSQL
SELECT
content_type,
COUNT(*) AS active_items,
COUNT(*) FILTER (
WHERE last_reviewed_at >= CURRENT_DATE - INTERVAL '90 days'
) AS fresh_items,
ROUND(
100.0 * COUNT(*) FILTER (
WHERE last_reviewed_at >= CURRENT_DATE - INTERVAL '90 days'
) / NULLIF(COUNT(*), 0),
2
) AS documentation_freshness
FROM content_items
WHERE archived_at IS NULL
GROUP BY content_type
ORDER BY documentation_freshness ASC;Pitfalls
Treating every edit as a review.→ Bot edits, formatting changes, and sync timestamps can make stale guidance look fresh. Store a deliberate review date when the source supports it.
Using one window for everything.→ A live incident runbook and a historical decision record should not share the same freshness policy.
Related
FAQ
What is a good documentation freshness target?
Set targets by content class. Teams often start with 90 days for fast-changing operational docs and longer windows for stable reference material, then tighten the policy where stale content creates real risk.