← Field Notes // Field Notes / 08

Documentation Is Infrastructure, Not an Afterthought

Jeff Hay, Portable Knowledge, LLC

Most engineering teams treat their test suite as something that has to keep working. Almost nobody ships a change that breaks half the tests and shrugs it off. The suite has an owner, a place it lives, and a consequence when it fails: the build goes red, and somebody fixes it before anything else moves.

I've never once worked somewhere that held documentation to the same standard, even though it breaks in the same way. A comment that's gone stale. A design doc that describes a version of the system three refactors ago. A README that was accurate the day someone wrote it and hasn't been touched since. A half-finished thought in a header comment. None of that fails loudly. It fails quietly, and it's only noticed at the exact moment someone needs it and it isn't there, or worse, it's there and it's wrong.

For most of my career that was a survivable kind of broken. A stale comment cost you twenty minutes while you read the actual code and worked out what was really going on. Annoying, not dangerous, because the person doing the reading knew to be suspicious of the comment the moment it stopped matching what they saw in front of them.

What actually changed

An AI coding assistant doesn't read that way. It has no instinct to distrust a comment that's been wrong for two years, or a design doc that describes a module that got torn out and rebuilt two releases ago. It takes the documentation at face value, because face value is all it has, and it writes code that's perfectly consistent with a story that was never true to begin with.

The output doesn't look like a mistake. It looks like a correct implementation of what the file told it to build. Nobody catches it in review, because it reads exactly like what a careful engineer would have written, if the engineer had believed the same wrong thing the file did.

I watched a version of this happen during a MATLAB-to-C++ migration. A translated function compiled clean and passed the obvious tests, and it was still wrong, because the original code carried an assumption nobody had ever written down. The AI tool didn't fail. The documentation did, by not existing, and the tool simply inherited a gap it was never told was there.

Treating documentation like infrastructure

That's why documentation belongs in the same category as your test suite and your CI pipeline, not in the category of "things we'll clean up eventually." Concretely, that means a few specific things, not a vague commitment to write more of it:

An owner, the way a service or a repo has an owner: a person accountable for it, whose job includes noticing when it drifts, and who can hand much of the checking to an agent.

Review in the same pull request as the code it describes, not updated later, if at all, by whoever happens to notice.

Some kind of staleness check, even an informal one: a periodic read-through against the actual code, the same way you'd check that your tests still reflect intended behavior, not just that they pass.

Coverage of what someone would need to know before touching the code safely. That's not what the function does line by line, which the code already says. It's why it does it that way, what it assumes about its caller, and what would break if that assumption stopped holding. A new engineer needs that, and so does an AI assistant.

Why this is worth the investment now

Most teams don't have anything close to this in place, and I don't think that's a knock on anyone. Skipping a disciplined documentation practice was easy to get away with, as long as "pointing something at the codebase" meant a careful, skeptical person reading it first and catching the gap themselves. That stopped being true the moment AI tools started generating real volume of code against systems nobody had the time to document properly.

The organizations that get ahead of this aren't the ones racing to adopt the newest tool. They're the ones treating the explanation of their own system as something worth maintaining on purpose, the same way they'd never let their test suite quietly stop meaning anything.