Documentation that stays true¶
Every page says when it was last checked, and a stale page fails the build.
Status: in daily use · checked Oct 23, 2026
In plain terms
Every page carries state, last-verified date, and evidence; stale pages fail CI, and the public edition is leak-tested after build.
last-verified date
and evidence] --> C{The checker, on every
change and every week} C -->|fresh and valid| OK[The page stands] C -->|stale, bad header,
dead link| F(CI fails):::guard F --> V[Re-check the claims,
then update the page] --> P
date and evidence] --> C{Checker: every
change, every week} C -->|fresh| OK[The page
stands] C -->|stale or
broken| F(CI fails):::guard F --> V[Re-check, then
update the page] --> P
Most documentation fails the same way: it was true once. This set is built around making the age and basis of every claim visible, and making stale claims fail a build instead of waiting for someone to notice.
Every page states what is true today¶
Each page starts with a small header that the site renders as a banner:
| Field | Meaning |
|---|---|
| state | daily, occasional, partial, built-not-running, abandoned in practice, unverified, or record for an immutable history page and index for navigation |
| last-verified | the day someone actually checked the page's present-tense claims |
| evidence | the files read and the read-only commands run, enough to repeat the check |
| visibility | private for anything that must not appear in the public edition |
The house style is Built; last verified: DATE; state: STATUS. rather than "works". A component that is built but off says so
plainly, and so does a page about an on-demand system that is currently switched off. If a page's state could not be established without
changing something or spending money, it says unverified and names the check that would settle it.
Stale pages fail CI¶
A validation script runs on changes and on a weekly schedule, so staleness fails visibly even when nobody is editing:
- a verified page older than its threshold fails (with a shorter threshold for pages on incident paths);
- a missing header, an invalid state, a missing evidence line, or conflicting dates fails;
- a page that must be private but isn't (by section, or by content) fails;
- a runbookAn alert-linked page describing what a rule means and first steps; generated stubs fill gaps without overwriting hand-written pages. Glossary without an enforcement stamp fails (the stamp says whether a mechanical guard backs its steps);
- addresses in source pages must be tokens resolved from the canonical configuration at build time; a hard-coded address fails;
- a link that resolves nowhere fails; links to repository files outside the site become links into the repository automatically.
A generated health page lists pages by state, the oldest verifications and every unverified page.
Runbooks for every alert¶
Alert rules link to runbook pages. Where a link pointed at nothing, a generator built the page from the live rule definition (what the rule evaluates, how long it must hold, where it is defined, how to query it now, first steps) and labeled it generated. It never overwrites a hand-written runbook, so improving a runbook means replacing the stub.
One source, two editions¶
| Internal edition | Public edition | |
|---|---|---|
| Audience | the operator | anyone with the link |
| Content | every page, including private ones; address tokens expanded to real values | only pages that are opted in twice (listed in an explicit navigation and flagged public) |
| Search index | all pages | only the public pages |
| Gate | strict build + page checks | strict build + page checks + leak test over the output |
The public edition is authored separately, not filtered from private pages. The leak testA scan of the built public site, search index included, that fails the build on any finding. Glossary scans everything that would be served, including the search index and the résumé PDF. It is itself tested: each rule has a test that plants a violation and requires the scanner to catch it.