Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Programmers will document for Claude, but not for each other

blog.plover.com

Post reply on HN
Print view View original

141–150 of 166 posts

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

#141

Post by jason_oster »

grumpymuppet wrote: post #126
__MatrixMan__ wrote: post #122

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.

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.

"Collaboration" is bullshit. https://news.ycombinator.com/item?id=47484519

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

#142

Post by scelerat »

Half of the purpose of me documenting things is to make certain that I fully understand the problem and its solution.

As I write out the explanation, if something doesn't make sense, that is a prompt for me to dig in and understand more fully either what I am supposed to accomplish and/or how I intend to do it.

That applies to everything from single-line comments on up to project READMEs and polished, customer-facing documentation.

One consistent frustration I have had over the years is that so much code is not documented or (worse) poorly documented. If there is a silver-lining to AI-assisted programming, it is that clear writing of goals and proposed solutions are rewarded with more accurate outcomes. It should have always been thus. but I'll take it.

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

#143

Post by GarnetFloride »

After 12 years of trying, my manager has finally convinced the boss that dev docs and user docs are different, because Claude made different documentation for different audiences.

When I was in tech support I wrote down the solutions to tickets, it took training the other support techs to read the knowledge base. It took 6 months but support call duration dropped 40%.

It also took training to get customers to read the knowledge base. That reduced calls by 60%.

Documentation has been disregarded by management since the 70s. Now suddenly it's important and its costing them a lot to try to play catchup.

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

#144

Post by Balooga »

In aerospace related industries there is a culture of writing and reading of requirements.

I system engineered for a major US satellite TV provider, and just the specification that defined the protocol for transmitting guide data over the satellite was about 640 US letter pages when printed.

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

#145

Post by noncoml »

__MatrixMan__ wrote: post #122

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.

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

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

#146

Post by chocrates »

noncoml wrote: post #145
__MatrixMan__ wrote: post #122

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.

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

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.

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

#147

Post by pixl97 »

qsera wrote: post #125
ang_cire wrote: 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.

This is not very surprising. The docs you write can only help if the person who is reading it have the same mental model of what ever thing that is being documented. Because the questons they want answered arises from what ever little subset of understanding they have of the thing. And this could be different for different people. And this is why LLMs are great for looking up docs. It makes any docs work for any one…

Adding to this, if an LLM can't get the right answer from your docs, its your docs that are bad.

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

#148

Post by noncoml »

chocrates wrote: post #146
noncoml wrote: post #145

Earlier quoted context omitted.

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

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.

You are right on that, but my point was how it just ignores what it read, even if it is in its context

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

#149

Post by pixl97 »

nunez wrote: post #139

It's pretty simple, really. Before agents, good documentation wasn't a metric that got you promoted or warranted a raise. Writing features takes time, so developers didn't do it. Agents require really strong documentation to work effectively. Almost every organization is volun-forcing their devs to use agents. Good documentation is now THE performance metric, except it's less about performance and more about keeping…

> most of that super detailed documentation is AI-generated, so there be dragons.

You can somewhat automatically test this by having some other AI agent/model read your docs and successfully implement it.

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

#150

Post by casey2 »

I was going to mention this too. Some of the API documentation I've read is downright puzzling, but whenever I see docs written for an LLM they always contain the exact relevant information I need to start working. [1]

I suspect the human docs are how they were taught to write and the LLM docs are what actually worked for the LLM.

[1] https://developers.openalex.org/guides/llm-quick-reference

Post reply on HN