WordloopOperations
Documentation Freshness
Review windows, freshness statuses, ownership rules, and stale-document handling for Wordloop documentation.
Documentation Freshness
TL;DR
Every active documentation page needs an owner, a review cadence, and a visible freshness state. Stale docs are not automatically wrong, but they are lower-trust until reviewed. Historical records such as ADRs and delivered bets are handled differently: they are preserved, corrected with explicit notes when necessary, or superseded.
Freshness states
| State | Meaning | Reader guidance |
|---|---|---|
| Fresh | last_reviewed is inside the review window. | Treat as current unless code or contracts prove otherwise. |
| Review due | The review window has passed. | Use with caution; verify against source of truth before making major changes. |
| Stale | The page is more than one review window overdue. | Do not use as authoritative without checking code, specs, traces, or owners. |
| Generated | The page is produced from code, contracts, or schemas. | Regenerate from source instead of editing by hand. |
| Historical | The page records past intent or decisions. | Preserve history; supersede or add correction notes instead of rewriting. |
Review windows
| Surface | Default review window | Status model | Source of truth |
|---|---|---|---|
| Principles | 6 months | Active | Docs and accepted ADRs |
| Service handbooks | 3 months | Active | Code, package metadata, architecture docs |
| How-to guides | 6 months | Active | Commands, workflows, and tested paths |
| Runbooks | 3 months | Active | Operational reality and incident follow-up |
| API reference | Every contract change | Generated | OpenAPI specs |
| Event reference | Every contract change | Generated | AsyncAPI specs |
| Database reference | Every schema change | Generated or active | Migrations and schema introspection |
| Glossary | 6 months | Active | Domain vocabulary and product language |
| Active bet TDD docs | Every material implementation change | Active | Current delivery intent and code reality |
| Delivered bet docs | No expiry | Historical | Archived design record |
| ADRs | No expiry | Historical | Append-only decision record |
| Agent skills | Every skill or mapped docs change | Active | Skill source plus mapped docs pages |
Required frontmatter
Active authored pages should include:
title: Documentation
description: One sentence describing the page.
audience: engineers
owner: docs-platform
last_reviewed: 2026-05-01
review_frequency: P6M
status: active
source_of_truth: docsGenerated pages should declare that they are generated where the generator supports it:
status: generated
source_of_truth: specs/core-openapi.jsonHistorical pages should not be forced into an active freshness cycle:
status: historical
source_of_truth: accepted-adrReview triggers
Review a page before its normal review window when one of these events happens:
- A package, language runtime, framework, or infrastructure version changes.
- A public command, environment variable, port, endpoint, event, or schema changes.
- A service boundary or data-flow diagram changes.
- A skill starts depending on the page for agent execution.
- An incident exposes missing or misleading operational guidance.
- An ADR supersedes a decision that the page explains.
- A user or agent reports confusion caused by the page.
Stale-page handling
- Classify the page. Decide whether it is active, generated, or historical.
- Find the source of truth. Use code, specs, migrations, traces, ADRs, or active design docs depending on the claim.
- Update the page or mark it historical. Do not silently keep stale active guidance.
- Update
last_reviewed. Only update the date after checking the claims, not after touching formatting. - Run documentation health checks. Confirm metadata, internal links, skill-doc references, and generated corpora are still valid.
- Review affected skills. If a skill depends on the page, check whether the skill's routing or verification steps need to change.
What not to do
- Do not refresh
last_reviewedwithout reviewing the claims. - Do not rewrite accepted ADRs to make them current.
- Do not edit generated reference pages by hand.
- Do not hide stale badges because they are inconvenient.
- Do not rely on humans to notice stale stack versions, command names, or broken links when a script can check them.
Commands
Run the health check from the platform root:
./dev docs healthRun the underlying docs script directly when working inside the docs service:
cd services/wordloop-docs
pnpm run docs:health