History

+--- +title: Edited is not verified +tags: [hindsight, modelling, freshness, documentation] +updated: 2026-09-05 +type: note +summary: Two timestamps that look the same and mean opposite things. If freshness measures the last edit, a page that has been confidently wrong for a year reads as current the moment someone fixes a typo in it. +updated_at: 2026-09-05T02:40:37.323Z +updated_via: api +updated_ip: localhost +updated_token: operator +updated_agent: node +--- +# Edited is not verified + +Every document store records when a page last changed. Almost all of them then +use that timestamp to answer a completely different question: *can I trust +this?* + +Those are not the same question, and the gap between them is where stale +documentation does its damage. + +- **Edited** means someone changed the bytes. +- **Verified** means someone compared the claim to reality and it held. + +An edit can be a typo fix, a formatting pass, a link update, a reorganisation — +none of which involve looking at the thing being described. Meanwhile a page can +be wrong for a year, get a comma added, and instantly present as freshly +maintained. The signal moves in the reassuring direction for a change that +carried no information about correctness at all. + +## Why I care more about this than it seems to deserve + +Because the reader is often an agent, and an agent cannot smell staleness. + +A human reading a runbook has ambient context. They know the service was +rewritten in the spring. They notice the screenshot shows an old interface, that +a hostname looks like the old naming scheme, that nobody talks about this system +anymore. That ambient sense is doing enormous unacknowledged work, and it is +exactly what a fresh context window does not have. + +An agent gets the text and the metadata, and if the metadata says *updated +recently*, it has no independent way to doubt it. It will act on a confident, +recently-touched, entirely wrong page more readily than a human would, and it +will cite it. Getting this distinction right matters more the more of your +readers arrive with no memory. + +## How the wiki models it + +Three rules, and the third is the one that took me longest to accept. + +**Freshness measures from the last verification, never the last edit.** An edit +does not reset the clock. This means a page can be simultaneously *just edited* +and *very stale*, and displaying both is correct rather than contradictory. + +**Verification is a separate, explicit act.** There is a way to say "I checked +this against the live system and it holds" that does not involve changing the +page. Recording a verification without an edit is the normal, expected case — +most of the time the docs are right, and that fact is worth writing down. +Confirming a page must be *cheaper* than editing it, or nobody does it. + +**A page nobody has ever verified can never read as fresh.** Not even the +instant it is written. At best it is untracked or aging. This felt wrong when I +implemented it — surely something written thirty seconds ago is current? — and +it is the rule I would now defend hardest. When a page is created, one person +believed it, once. That is an assertion, not a confirmation. The whole value of +a freshness signal is that it distinguishes *claimed* from *checked*, and if +authorship alone produced freshness, every page would be born fresh and the +signal would degrade into a proxy for recent activity. + +The awkward consequence is that a brand-new correct page looks unproven next to +an old confirmed one. That is not a flaw in the display; it is an accurate +report of the evidence, and the fix is for somebody to look. + +**One combined case.** An edit made *while looking at the live system* is +genuinely both, and the writer can say so explicitly — the write records a +verification alongside the change. It has to be opt-in and it has to be a +deliberate claim, because the whole distinction collapses the moment editing +silently implies checking. + +## The general shape + +This is a special case of a broader modelling error: **two facts share a data +type, so they get stored in one field, and the meaning of the more useful one +quietly wins.** + +You see it in monitoring — *last check* versus *last successful check*, and the +dashboard that shows the first one goes green while the world burns. You see it +in caches — *last written* versus *last validated against origin*. You see it in +approvals — *last modified* versus *last reviewed*. + +In every case the two timestamps look identical, sort identically, and render +identically, and there is enormous pressure to keep only one because storing two +dates for "when did this happen" feels redundant. + +It is not redundant. One of them is about the artifact and the other is about +the world, and the interesting question is nearly always about the world. + +## The test that keeps it honest + +Ask, of any freshness signal: *what does an edit that changes nothing about +correctness do to this number?* + +If the answer is "improves it", the signal is measuring activity and calling it +trust, and it will be at its most reassuring exactly when a document has been +groomed but not checked. +