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

121–130 of 166 posts

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

#121

Post by docheinestages »

matheusmoreira wrote: post #119
docheinestages wrote: post #89

Generating tonnes of documentation is easy, but it can easily get outdated and so much that no one would read it. Ideally, code should be the single source of truth. Documentation should be generated dynamically and upon request to not go stale. The amount of detail and how far to dig in should be up to the end user.

I simply added a documentation agent to my parallel code review skill. Automatically finds documentation drift.

That could work, but there's still the chance that things could diverge if multiple people are working on a project and not everyone is as diligent as you. With LLM context windows continuously growing, agents should be able to scan the whole repository and even relevant repositories on the fly, provided they contain the truth and only what's necessary (i.e. minimal commentary).

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

#122

Post by __MatrixMan__ »

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.

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

#123

Post by marcosdumay »

reaperducer wrote: post #17
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.

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.

> which solves the problem

Did it solve the problem? If so, why people had to keep repeating it everywhere the entire time?

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

#125

Post by qsera »

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 as long as the information is present in the doc.

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

#126

Post by grumpymuppet »

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

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

#127

Post by pravj »

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

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.

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

#128

Post by thisisit »

I have at both ends of this problem.

Documenting but people not reading and still asking question. I have tried some what successfully asking them if they have read the document. Because sometimes people are unaware it exists. There are those who insist on answer and these are people who I give delayed response.

On the hand I have seen people who say stuff like why don't you read the code. These people are now using AI to write documents.

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

#129

Post by vitally3643 »

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.

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.

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

#130

Post by satvikpendem »

vitally3643 wrote: post #129
grumpymuppet wrote: post #126

Earlier quoted context omitted.

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.

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.

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/

Post reply on HN