What makes documentation trustworthy: the three signals readers check before believing a page

Readers use the date as a proxy for accuracy before reading a word, and platforms feed the habit by showing last-edited automatically. The problem is that last-edited lies in both directions: a typo fix makes a wrong page look current, and a correct page about a stable system looks abandoned. The stronger signal is last-verified, a stamp a human sets only after checking the page against reality, distinct from the edit timestamp the platform maintains.

The stamp works because it is falsifiable: it names a date and a person, and a reader who finds a lie under a fresh stamp knows exactly what broke down. Pages missing their expected stamp are equally informative, which is what makes the stamp queryable infrastructure for documentation freshness metrics, not just reassurance.

---
title: Payments service runbook
owner: "@team-payments"
last-verified: 2026-08-10
verified-against: release 2026.32
---

An owner in the header changes the reader's risk calculation: a page signed by the payments tech lead can be wrong, but someone specific answers for it, and there is an obvious person to ping before acting on a doubtful claim. An anonymous page offers neither, so prudent readers treat it as rumor. Team names work; individual names attached to a role work better, provided ownership metadata survives departures, the mechanics covered in who owns architecture documentation.

Ownership also feeds the first signal: an unowned page has nobody to stamp it, so the two signals decay together, which readers notice as a pattern long before any dashboard does.

Engineers spot-check by instinct: before investing in a page, they test its cheapest verifiable claim. If the command runs, the service name resolves, the port answers, the page earns provisional trust; if not, reading stops. This is rational Bayesian behavior, and it means a page's credibility rides disproportionately on its most checkable claims, wherever they sit.

Design for the check instead of hoping to dodge it: put a claim the reader can verify in seconds near the top, keep exact names and commands over paraphrase, and cut claims nobody can test. A page that invites verification and survives it converts skeptics; a page of untestable generalities cannot even be trusted in principle.

Trust in documentation is evaluated per source, not per page: a reader burned twice stops checking the wiki at all and routes every question to a human, which is why teams with hundreds of fine pages still see the wiki bypassed on the strength of a few prominent lies. The asymmetry is brutal, one bad experience outweighing many good ones, and the senior engineers absorbing the redirected questions pay the bill, one input to the cost of outdated documentation.

The repair sequence follows from the asymmetry: cull before you fix. Archiving every page nobody will re-verify removes the encounters that reset trust to zero, and a smaller surface of stamped, owned pages can then rebuild it. The full recovery playbook is in stale documentation, and the terminal form of the disease has its own page in wiki rot.

Diagrams take the spot check harder than prose: a reader who spots one missing service dismisses the whole picture, because a diagram asserts completeness the way a paragraph does not. A pasted screenshot also carries no trust signals at all, no stamp, no owner, no way to tell which year it describes.

A live embed changes what the artifact is evidence of: an image served from the source diagram, re-rendered when the diagram changes, means what the reader sees follows the current source within minutes rather than being frozen at paste time. It shifts the question from is this copy current to is the source maintained, one question instead of one per copy. The honest limits: the project must be shared public for the embed URL to exist, and a human or an MCP-connected agent still has to update the source when the architecture changes, since nothing watches the repository by itself.

• Stale documentation
• Wiki rot
• Documentation freshness metrics
• Documentation review cadence