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.
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.
Agents are phenomenal at pattern matching and syntax execution, but they struggle with architectural philosophy and human intent. We still need words to contextualize the boundaries. A spec can define an endpoint, its parameters, and its payload. What it can't capture is the nuance of why a specific architectural trade-off was made, or the implicit historical context of a legacy edge case.
Prose provides the guardrails for non-deterministic systems. Even if that prose is ultimately consumed by a machine rather than a human, the written word remains the highest-leverage way to transmit intent.
This doesn't mean we need to return to the days of manually maintaining massive, static wiki pages. Automation has a massive role to play here. Cascading automation—where documentation is dynamically generated alongside code changes—is incredibly powerful.
But there’s a trap here: slop describing slop is entirely useless.
If we completely hand off documentation generation to unchecked LLMs, we end up with a feedback loop of hallucinated context describing rapidly shifting code. It creates noise, not clarity. The Key is Oversight.Even if the documentation is entirely bot-driven, human engineering oversight is non-negotiable. We need to gut-check and validate the generated prose to ensure it represents an accurate, high-level explanation of the broader context. Think of generated docs as a non-deterministic cousin of the API itself—highly valuable, but only if kept on a tight leash.
Right now, the single biggest blocker to this new paradigm is trust. The current lack of a "gut-check" trustworthiness metric for documentation is a massive bottleneck for both human developers and autonomous agents.
In the open-source eras of the past, we relied on crude but effective reputation proxies. If a repository had 10,000 GitHub stars, a vibrant issue tracker, and recent commits, you could reasonably assume the project (and its documentation) was stable.
We don't have a reliable reputation system for the AI era yet. The absolute novelty of the moment, combined with how incredibly easy it is to game automated metrics, means everything feels a bit unanchored.
The next major shift in developer tooling won't just be about making agents faster or code generation cleaner. It will be about solving the reputation problem—building systems that can automatically verify, score, and guarantee the trustworthiness of the knowledge bases our software relies on.
Until then, don't delete your markdown files. The machines still need to read between the lines.