Some months ago I read Samuel Albanie’s post Documentation Considered (Increasingly) Harmful. In it, Albanie argues that documentation quickly goes “stale” and doesn’t reflect the real state of a codebase, especially when it’s being frequently updated.

Stale documentation is a real problem, but in my experience agents are simply not good enough yet at poking through a codebase to explain setup, ordinary running of code, testing, or architecture. I have frequently seen them confuse basic terms and had to correct them. Agents are also optimised for writing code, not for explaining things well – so the latter takes a couple of tries.

Documentation’s not dead just yet, people.