Writing
Documentation used to be written for the human sitting next to the code — tutorials to onboard them, guides to persuade them, references they would skim once and never open again. That reader is gone. The thing reading your docs now is an agent at 2 a.m., with your page as its only context and no patience for your voice. It needs the shape of the thing, the exact inputs and outputs, and a check it can run — everything else is a token tax you charge every reader, forever.
Generate, don't hand-write
Every hand-synced document rots: the code moves on, the paragraph stays behind, and the agent can't tell which one is lying. The fix is to make documentation a build artifact. API references generate from the code itself — FastAPI derives OpenAPI schemas straight from Pydantic models, so the documented shape and the enforced shape can never disagree (FastAPI, OpenAPI). This site does the same everywhere it can: the sitemap and the machine-readable index generate from the same route list that serves the pages, so a new page can't exist without being listed.
The old information architecture already knew documents have kinds — tutorials, how-tos, reference, explanation each do one job (Divio). The agent era adds one rule on top: reference is generated, guides carry checks, and nothing is copied by hand between two places.
One shape per fact
An agent doesn't read your docs; it parses them. Tables beat prose, explicit beats implied, and stable identifiers beat clever names. Every skill in this bank carries the same five fields — id, prompt, why, checks, tokens — in the same order, so the hundredth skill reads exactly like the first. State inputs and outputs up front, name units in field names, and never let one fact live in two wordings: the map routes, the leaves answer, and the agent fetches only what matches (Anthropic).
End every doc in a check
A document nobody can verify is a rumor. Every bank skill ends in checks a runner can execute; every release carries a version and a signature so an agent can confirm what it fetched is what was published. Humans judge two things — tests pass, and the screenshot looks right — and the docs serve both: the check for the machine, the verdict for the person. Write the check first; the paragraph above it is just the check explained.