It is primarily a principal agent problem, with a hint of marshmallow test.

If you are a developer who is not writing the documents for consumption by AI, you are primarily writing documents for someone who is not you; you do not know what this person will need or if they will ever even look at them.

They may, of course, help you, but you may not understand that, have the time, or discipline.

If you are writing them because the AI using them will help you, you have a very strong and immediate incentive to document the necessary information. You also have the benefit of a short feedback loop.

Side note, thanks to the LLMs penchant of wiping out comments, I have a lot more docs these days and far fewer comments.

The moment you write documentation it becomes stale. It's additional debt you've incurred and the upkeep must be payed every modification to the code.

That doesn't mean you should skip it - but it's vital to recognize the costs.

When I joined my current company they had extensive documentation on several systems, all of it outdated, stale or even just straight up wrong. I wasted cumulative weeks depending on other programmers to have properly documented things.

It's still worth doing: but you _must_ continually pay the debt down.

Yeah this is really interesting. My money is 80% on number 1. The good developers I know (I'm not among them) are very practical and results driven. If they see something is useful for their goals, they use it. There's the time delay that you mentioned, and also that there's no direct feedback at all via misalignment. You'll probably get a scolding if your code breaks or you miss deadline, but if someone else complains about documentation to manager, that's one more degree of separation. If the manager doesn't directly feel the pain, he/she won't pay as much attention.

Edit- I'm basically repeating the poster who said it's principal agent problem.

Probably all the same reasons tech debt exists in the first place: business pressure, poor design, lack of resources. It used to be expensive to keep good documentation up to date as the code changes.

I've built an agent that builds documentation for code bases and you are 100% right. Having big picture documentation is important, but having bite size explanations about why some components work a certain way is more important. Making sure the AI doesn't have to infer behavior from code is really powerful. Even going as low level of reference docs. Even though devs would prefer that a method be self-Explanatory, it helps to also have plain english explanation about what's happening in a class or method.

onboarding devs won’t risk looking dumb to complain about the bad docs, the authors already have a mental model, and writing them out fully helped others at expense of job security.

When doling bad docs to a stupid robot, you only have yourself to blame for the bad docs. So I think it’s #2 + #3. The big change is replacability going from bad to desirable (replace yourself with agents before you are replaced with a cheaper seat)

This is nothing new. v1 of something is always easy. Now in the coding assistant world, everything is v1. Let the tools go through a few deprecation cycles, weird things being added that don't map to the original intent, floods of overlapping tools and docs and everything else that someone has to reconcile, different LLM technologies that you need to support and adapt to, etc., and then see how things look.

I think all three things you mention come into play, but it's a bit early to judge whether the world has shifted or whether this is mainly a result of everything being fresh and new.

> What was the barrier to creating these documents before?

In a proprietary system, there is pressure against creating quality technical documentation because it can be used to train your replacement. Writing docs solely for your own benefit, or your colleagues' benefit, is also dubious because you already know the things you wrote. Although returning to a thing you made months/years ago can be painful, it's not the day-to-day common case in enterprise software development.

AI assistants flip the incentives. Now, your docs are helping to steer your personal digital goblin in the right direction. The docs are tangibly augmenting your own abilities.

I think 2 is the big one; I also built a tool to maintain these fragments, and it's like, huh, this is just ... developer onboarding documentation?

Here’s the thing: I wrote the code, annd it’s fresh in my human context window. so I already know everything about it everything’s obvious to me. I can’t forget it all and then read what I wrote afresh, in order to figure out what I’ve left out. We chose Kafka because it was the obvious choice because of all these assumptions that I had in my head that I didn’t even know I was assuming.

Program will evolve and documentation will go out of date before it's gonna be read a single time. So a variant of 1)

Personally I don't write documentation because I don't read documentation. It's too often pure garbage, less reliable than 2023 LLM output so I just skip it and go to the source code.

I would read documentation written for AI because I know for a fact that it describes the thing accurately enough if the system works. Human addressed documentation almost always has no verification.

> 2) The tools can help build them. Building good docs was always hard. Especially if you take the time to include examples, urls, etc. that make the documentation truly useful. These tools reduce this cost.

I would just be a little cautious about this, for a few reasons: (a) an expectation of lots of examples and such can increase the friction to capturing anything at all; (b) this can encourage AI slop bloat that is wrong; (c) bloat increases friction to keeping the key info up to date.

> 3) Many programmers are egotists. Documentation that helps other people doesn't generate internal motivation. But documentation that allows you to better harness a computer minion to your will is attractive.

There are also people who are conflicted by non-ideal trust environment: they genuinely want to help the team and do what's right for the business, but they don't want to sacrifice themselves if management doesn't understand and value what they're doing.

> Any other theories?

Another reason is that organizations often had high-friction and/or low-trust places to put documentation.

I always emphasize low-friction, trusted engineering docs. Making that happen in a small company seems to involve getting everyone to use a low-friction wiki (and in-code/repo doc, and when to use which), migrating all the doc that's strewn all over random SaaSes that people dropped it, showing people how it's done.

It must be seen as genuinely valuable to team-oriented, mission-oriented people.

Side note: It's very difficult to try to un-teach someone all the "work" skills they learned in school and many corporate jobs, where work is mostly directed by appearances. For example, the goal of a homework essay is to have what they deliver look like something that will get a good grade from the grader, but they don't care at all about the actual quality or value of it, and it has no other purpose. So, if you drop that person into a sprint with tasks assigned to them, the main goal will be to look good on what they think are the metrics, and they will have a hard time believing they're supposed to be thinking beyond that. (They might think it's just corporate platitudes that no one believes, like the Mission Statement, and nod their head until you go away.) And if they're told they're required to "document", the same people will go into that homework mode, and will love the generative-AI tools, and not reason about the quality/value/counterproductiveness of dumping that write-only output in whatever enterprise SaaS someone bought (decided in often another example of "work" done really understanding or caring what they were doing, but for appearances).