There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like this: We’re living in the era of agent-driven development. If an AI agent can read the raw source code or parse an OpenAPI specification instantly, why waste human engineering hours writing prose? Code churns too fast anyway, and human-written docs are outdated the second they’re committed.
It’s an attractive, black-and-white view of the world. It’s also completely wrong.
Chasing strict determinism in your source of truth is a pipe dream. Code and specs tell a system how something works, but they are fundamentally incapable of explaining why it was built that way in the first place.
The Intent Gap: Why Code Isn't Enough
Even if you’re building entirely for a downstream consumer of AI agents, there is a massive, structural gap between a raw API specification and an operational reality.
