Documentation Considered (Increasingly) Harmful

In 1968, Edsger Dijkstra published a legendary article titled “Go To Statement Considered Harmful,” arguing that its use obfuscated program flow and should be abolished.

Today, I want to make a related, if more modest, claim: technical documentation is becoming increasingly harmful.

My reasoning is simple: Documentation is a form of caching.

In systems design, caching is the deal we make with the devil to trade correctness for speed. We store a pre-computed result to avoid the expensive work of re-deriving it from the source of truth. Every experienced engineer knows this is a dangerous game. The cache can become stale, the environment in which it was computed can change, and an incorrect assumption can lead to catastrophic failures. Google’s desire for hermetic builds is related to this fear.

Documentation is a human-driven cache. An engineer invests significant cognitive effort to understand a piece of source code—its function, its interfaces, its limitations. They then “cache” this understanding in a human-readable document. The goal is to save the next person the cost of that initial computation.

For decades, this was a good trade. The cost of a human parsing raw source code was so high that the risk of a stale documentation cache was worth it. But that is no longer the case.

With models like Gemini that can ingest and reason over million-token contexts, the cost of "on-the-fly computation" is plummeting. We can now ask an AI to read the code—the one and only source of truth—and generate an explanation on demand. The cost-benefit analysis has flipped.

We should be purging the stale cache, especially for documentation that describes the what and how of our code. Instead of pointing a new teammate to README.md, we should be giving them an AI agent and pointing them to the src/ directory. The higher-level why—the architectural trade-offs and business logic that shaped the code—is a different story, but its days of living in static documents are also numbered.

Of course, we are not there yet. The models still make mistakes.

But the end of documentation as we know it is in sight.

Weekly ecosystem links

John Carmack describes what he’s been up to. The legendary software engineer is battling RL on Atari games, and is hoping for better benchmarks.

The race for LLM “cognitive core” - Karpathy describes a possible future direction: lightweight LLMs that sacrifice encyclopaedic knowledge for capability.