Live data from Hacker News

Programmers will document for Claude, but not for each other

blog.plover.com

11–20 of 166 posts

Re: Programmers will document for Claude, but not for each other

#11

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.

Ahh yes, the documentation for claude. When someone created a CLAUDE.md, then changed some stuff around and when I later had to touch that repository my claude was hallucinating classes, functions and architecture that was already long gone! I just deleted the CLAUDE.md, since I had no mood to "fix" it.

Couldn't you have claude correct the CLAUDE.md?

Re: Programmers will document for Claude, but not for each other

#13
I've never had this problem.

The problem I have had is other developers expecting me to maintain documentation for their tools. To the point that they wage stupid inter office wars because they don't want to learn a command line utility with 20+ years of documentation itself.

Re: Programmers will document for Claude, but not for each other

#14
post #9

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.

Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case:

  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.

Re: Programmers will document for Claude, but not for each other

#15

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).

[dead]

Re: Programmers will document for Claude, but not for each other

#16
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. People eventually learned to stop doing that because I always provided the docs because I saw that coming. 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.

Re: Programmers will document for Claude, but not for each other

#17
post #9

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.

It's been this way since the beginning.

That's why Usenet is full of posts reading "RTFM."

For some reason, instead of telling people to do that, which solves the problem, we just stopped writing manuals altogether.

Post reply on HN