Most engineering docs die the same way: written once at high effort, read twice, then silently wrong for the next two years while still ranking first in search. The problem usually isn't writing quality — it's that the doc was never designed to be found, trusted, or maintained, three properties that have nothing to do with prose style.
Write for the Question, Not the Topic
Docs organized around "here is everything about X" force every reader to find their specific question inside a wall of context they didn't ask for. Docs organized around the actual questions people bring get read and get reused, because a reader can scan headers and land directly on their answer.
Bad heading: "Authentication"
Better heading: "How do I get a token for local development?"
"Why does my token expire after 15 minutes?"
"How do I rotate a service account's credentials?"This isn't just a formatting preference — it changes what gets written. "Authentication" invites a comprehensive architecture explainer; "how do I get a token for local development" forces the answer to actually be a procedure, which is what most readers of that doc need at that moment.
State Freshness Explicitly
The single most damaging thing a doc can do silently is go stale without saying so — a reader has no way to distinguish "current and correct" from "accurate as of a system that no longer exists" unless the doc tells them. Two cheap habits fix most of this:
- A visible "last verified" date, separate from "last edited" — someone fixing a typo shouldn't reset the trust signal for content they didn't actually re-check.
- An explicit scope statement at the top: what this doc covers and, just as usefully, what it doesn't — "this covers the staging deploy process; production deploys are in [doc]" saves a reader from applying staging instructions to production and finding out the hard way.
Owned Docs Survive; Orphaned Docs Rot
A doc with no named owner degrades the moment the system it describes changes, because updating it isn't anyone's job — it's everyone's, which in practice means no one's. Docs that stay accurate over years tend to share one mechanism: an owner attached at creation, a team rather than always an individual since individuals leave, and that ownership is discoverable from the doc itself, not buried in a wiki permissions page nobody checks.
Delete Aggressively
Doc quality is a subtraction problem as much as an addition problem. A wrong doc that ranks well in search is worse than no doc at all — it actively costs readers time and can lead them into wrong actions with more confidence than "I couldn't find anything" would. Treat doc deletion as a normal, low-ceremony action: when a system is deprecated, its docs get deleted or explicitly marked deprecated in the same change, not left to be discovered wrong by the next confused reader.
Optimize for Skimming First
Most doc reads are not cover-to-cover — they're a scan for one fact, under time pressure, often during an incident. Front-load the answer, then the reasoning: a reader who needs the command should find it in the first few lines, not after three paragraphs of architectural context they can come back for if they want it. The doc that respects a skimming reader gets trusted enough to become someone's next bookmark; the one that doesn't gets replaced by a Slack DM to whoever remembers the answer, which is where undocumented tribal knowledge comes from in the first place.