sure, but those documents are generally just as useless because they're 70% complete, 10% indirect and 20% wrong.

Unstrutuced slop is no better at best, and much worse at worst.

1. Claude's productivity is your productivity, but team's productivity is not your productivity.

2. Claude will actually read what is written (well parse for autocompletion, not actually "read", unless you are under AI-psychosis).

Some people like to brag about how productive they have become with AI, but I see them spending a few hours a week adjusting which model to use, trying the new shiny harness or writing Claude skills.

Are you really more productive if instead of coding you are spending your time tweaking the AI to do what you want?

yeah, because claude will actually read the docs

I've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it.

  1. Immediate better output from the machine OR...
  2. Being sidelined for career promotions because you spent so much time making sure documentation was accessible while everyone knows they can ask you instead of reading it, and you will answer.

I've been noticing that too. "Hey, the normal documentation for our software of a crude API list describing what each command is and each of its parameters isn't good enough for the AI. We need to provide the AI with instructions on how to use the software to solve common problems"

Uh, you needed to do that for humans too. You just didn't. There's a reason everybody scrolls to the bottom of man pages ASAP.

[delayed]

Yes, I've already "abused" this a couple of times to get some docs written that we had needed for years but hadn't been written. All kinds of docs; code documentation, deployment documentation, overview documentation, architecture documentation. APIs that we kicked around as being useful for years are now actually on track to be written because we can't integrate non-existent APIs into MCP servers or skills.

On the one hand, I also feel like "come on, couldn't we have done this earlier?"

On the other hand... the costs of the docs have decreased. Simply firing a frontier model at your code base doesn't always produce perfect docs but it's a heck of a good start. I do recommend some tuning in the request, e.g. I like to explicitly ask the AI to document data flow rather than the usual list of "here's this component, here's this component, here's this component", but it's pretty easy.

And the utility of docs is now much higher. I really just recently moved into the classical "architect" role and in some ways I'm glad it wasn't much sooner, because my GenX cynicism tells me that nobody ever reads the architecture docs. OK, OK, sure, technically nobody is a bit too strong. Sometimes, some particularly intrepid or conscientious souls surely read them at some point. But from my own experience I could count on being able to hand out API docs, structure docs, flow docs, and their primary utility was that when someone tried to deflect responsibility with "but but but they didn't provide any docs" they couldn't, because I had. And they made a great background on the shared screen as I had to walk someone through the entire thing in a meeting anyhow. They were more a really specialized meeting transcript than something I could provide in advance and expect much out of.

But now, if nothing else, AI will read the documentation. I can tell people to pull it in, and while it doesn't mean all my problems go away, there is now a much cleaner path for me from "writing an architecture doc" -> "lines of code in somebody's repo" than there was pre-AI. My architecture docs are now somebody else's prompts. The utility of this sort of documentation skyrockets compared to the old days.

So, when the costs decrease and the benefits increase, it isn't a surprise that suddenly, it's easier to get some of these things done that we "knew" we needed for a long time, but now with the new cost/benefit ratio can cross the action threshold.