Ownership And Freshness designed
The portal is now large enough that source links are not enough. Each page needs an owner, review domain, freshness risk, review cadence, and trigger for when it must be updated.
Required Metadata
Every portal page must declare:
| Field | Meaning |
|---|---|
owner | Team or workstream responsible for keeping the page useful |
review_domain | Review lanes that should approve material changes |
last_reviewed | ISO date for the most recent content review |
review_cadence | monthly, quarterly, semiannual, or annual |
freshness_risk | low, medium, or high |
sync_trigger | What source change requires portal review |
These fields complement the existing audience, visibility, status, and
source_docs metadata.
Freshness Risk
| Risk | Use when | Default cadence |
|---|---|---|
| High | Page explains release posture, security, API behavior, active roadmap, current operations, or generated artifacts | Monthly |
| Medium | Page explains architecture, product strategy, developer onboarding, or runbook entry points | Quarterly |
| Low | Page is mostly stable reference, historical framing, or glossary content | Semiannual or annual |
Sync Trigger Examples
| Page type | Trigger |
|---|---|
| API/reference | OpenAPI, AsyncAPI, auth, error, or SDK artifact change |
| Product | PRD, UX journey, IA, competitive, or page contract change |
| Architecture | Boundary, route, domain, deployment, shared-service, or open-decision change |
| Security | Control, gap, threat, release gate, or evidence requirement change |
| Ops | Runbook, platform baseline, release, observability, or incident workflow change |
| Developer | App SDK, manifest, artifact, credential, or example workflow change |
Enforcement
make docs-portal-check validates required ownership and freshness metadata.
The stricter source-drift gate is available in blocking mode with
DOCS_PORTAL_ENFORCE_SOURCE_RECENCY=1: if a portal page claims a canonical
source doc and that source doc changed after the page was last reviewed, the
check fails until the page is re-reviewed or intentionally updated. The goal is
not bureaucracy; it is to make stale pages visible while the portal is still
easy to fix.