News for hackers. Stuff that matters.

A comment on Programmers will document for Claude, but not for each other.

Re:Programmers will document for Claude, but not for each other by __MatrixMan__ on Friday June 05, 2026 @12:18PM (#48414647)
Yeah, because Claude is willing to read other documentation in order to understand mine. When I'm asked to write docs for humans I have to work four times as hard because 3/4 of that work is getting the audience up to speed just so I can start documenting the actual thing. And then they don't read it and ask me to explain it to a meeting anyhow.
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by pravj on Friday June 05, 2026 @12:40PM (#48414994)
Strongly agree with this. Long before 2022 (ChatGPT), I remember saying to someone at work, "We need to build a reading culture for a writing culture to thrive."

I used to envy and take inspiration from other workplaces where good [but not necessarily good-only] writing was respected; where a pre-read is really read before the meetings, thoughtful comments were made on it, etc.

AI workflows have obviously simplified documentation generation along with the code, but we had to work on our product/engineering practices to generate meaningful documentation, and not just vestigial/temporary documents in the process. On this particular point, we've made positive progress lately.

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by nunez on Friday June 05, 2026 @01:18PM (#48415523)
> And then they don't read it and ask me to explain it to a meeting anyhow.

All of this!!!!

I still write docs so that I have them for myself when I invariably forgot what I wrote six months later, but, yeah, writing a detailed onboarding doc only to end up paraphrasing it to someone over Zoom is peak frustration. (Unless I'm doing so because my docs aren't clear. That is good feedback.)

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by noncoml on Friday June 05, 2026 @02:24PM (#48416313)
Claude reads it alright, and then ignores it.

Dev: Why did you run Y command? Doesn’t it clearly say in README.md to use X command instead?

Claude: You are right to be frustrated. I ignored it because “some generic excuse”. It won’t happen again

Narrator: It will happen again

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by chocrates on Friday June 05, 2026 @02:47PM (#48416588)
Asking it why it did something will not get you usable data. It will read what it did in the context and hallucinate a reason.
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by noncoml on Friday June 05, 2026 @02:55PM (#48416696)
You are right on that, but my point was how it just ignores what it read, even if it is in it's context
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by coldtea on Saturday June 06, 2026 @09:57AM (#48425218)
It read the context and randomly picked a way around what it asked. That's just how it works. Other times, it will follow it.
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by grumpymuppet on Friday June 05, 2026 @12:34PM (#48414881)
I bet a huge amount of that is on your head, or if it is factual, a function of a toxic work culture where people are primarily incentivized to "outperform one another" rather than arrive at collaborative solutions.

The wealthy/owner class once again consume all of us -- here through AI -- because we cannot agree to work together.

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by Kirth on Friday June 05, 2026 @03:31PM (#48417080)
This was also my first thought when reading the title: because Claude is a tool you use and co-workers are either competitors or people preferably dependent.. an anti-pattern and not good culture but sadly the norm.

That's not to say that the help-vampires the parent mentions don't exist. I think we culturally are afraid of pushing back against them: telling them to RTFM and then come back.

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by closeparen on Friday June 05, 2026 @12:53PM (#48415192)
Many companies, including in their software development functions, are oral cultures rather than literate cultures.
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by jason_oster on Friday June 05, 2026 @01:41PM (#48415821)
"Collaboration" is bullshit. https://news.ycombinator.com/item?id=47484519
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by vitally3643 on Friday June 05, 2026 @12:42PM (#48415017)
No. It is a well established fact that the majority of users will not read documentation of any kind. This is not a new observation, it's been a meme in developer circles from the first day computers showed up in the workplace.

You can step off your high horse now.

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by satvikpendem on Friday June 05, 2026 @12:47PM (#48415104)
It's not just docs too, it seems to be some general phenomenon that users don't read most anything on screen.

This is from almost 20 years ago [0] and the original stretches back almost 30 years now [1].

[0] https://www.nngroup.com/articles/how-little-do-users-read/

[1] https://www.nngroup.com/articles/how-users-read-on-the-web/

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by socalgal2 on Friday June 05, 2026 @01:21PM (#48415563)
In my defense. (1) I can't find the docs (2) I can't find the relevant docs (3) after having read several irrelevant docs they still don't answer my question but the question I need answering isn't actually in the docs.
[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by pixl97 on Friday June 05, 2026 @01:38PM (#48415768)
I would add on that if AI doesn't seem to understand your docs then humans are going to have an even harder time.

I've seen where when AI is asked a question on how to use some particular feature of a piece of software it couldn't get a working answer. I read the documents myself and was just as confused. Then looked up customer tickets around said feature, and they were confused too.

I've taken that as a pretty good metric that if AI can't parse your documentation, your documentation is bad or wrong and needs to be rewritten.

[ Parent | on HN ]
Re:Programmers will document for Claude, but not for each other by isityettime on Friday June 05, 2026 @06:35PM (#48419228)
Most of the internal docs I write are basically pointing people to canonical docs that already exist, and sometimes also summarizing docs that already exist.

It seems to help, perhaps somewhat surprisingly.

[ Parent | on HN ]