Documentation is Always Wrong
0001-01-01
It’s long been acknowledged that documentation is obsolete as soon as it’s written. Anyone reading this has worked at a software company that had some crusty confluence, with pages written a year or two ago that bear no relation to what currently exists. This is the nature of software development - you’re supposed to change and create things. It’s development, after all.
Worse, documentation only reflects one or two author’s view of things. Very often, engineers building good things and making good decisions are busy doing that, and are not busy writing about it. They’re interested in getting it right, and solving the next problem.
Everything about agentic is documentation
Inevitably, someone will get tired of models creating code that isn’t up to the organization’s standards. We need a certain log format, or trace segments, or error feedback. Can’t we just codify those into organization-wide Skills that every claude instance uses? You might even have a company with a bunch of standards written in RFC-like format, which dictate the big picture of software standards. Surely, if we just write everything down, the LLMs will do the right thing when we ask it. Usually this person is a manager, and [[Software Managers have Dunning-Kruegar]].
But of course, the whole point of things like Claude or Codex is that they greatly accelerate how fast code is written, systems are launched, and things are changed. They increase velocity. If documentation was impossible before, it’s more impossible now. How are we supposed to keep agents and skills updated when those very agents and skills are being used to speed up the change in agents and skills? [[Maximalism of the Gaps]] would argue that this kind of self-updating is something the LLM itself could do - as it creates services or finds gaps in standards it could update them. But the whole point of making these was to cover up for the fact that the LLM can’t do this stuff, because [[Models Have a Limit]] and [[Userland is Not Enough]]. We’re not making a self-improving superintelligence, we’ve made a very expensive engine for tech debt.
