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

131–140 of 166 posts

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

#131

Post by closeparen »

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.

Many companies, including in their software development functions, are oral cultures rather than literate cultures.

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

#132

Post by fer »

serf wrote: post #96
fer wrote: post #24

Earlier quoted context omitted.

If you tell it to. Otherwise you might get the classic "You're absolutely right – I made that up. Let me look at the documentation"

if you find yourself saying 'if you tell it to' a lot about LLMs that usually just says something about your prompting methods. or, in other words , if you want the thing to always read the documentation then make that a strongly highlighted point both in pre-prompts, active prompts, and memory.

It mustn't always nor never. It should follow a best judgement based on the .md, toml or whatever you use; in the end it's up to the LLM to decide which registered tools/mcps are used, and if the LLM is confident about some bs it will use that confidence instead of the tool.

When people complain about it, it's more often a gap between different knowledge domains and hard to measure characteristics of the environment, than it is an actual "you're using it wrong".

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

#133

Post by reaperducer »

marcosdumay wrote: post #123
reaperducer wrote: post #17

Earlier quoted context omitted.

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?

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

Because people are lazy, or new, or for some other reason turned to asking questions of strangers in a public forum rather than making the small effort to look for the solutions on their own.

It's the same reason that Let Me Google That For You was invented.

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

#134

Post by zahlman »

> I'm a little slow so it took me until this week to think of a better version of this: at the end of the project I now ask Claude to write up from scratch a detailed but high-level explanation of what problem we were solving and what changes we made, and I commit that. Not just running notes, but a structured overview of the whole thing.

I feel like the right place for this information is in the Git history itself. If it doesn't logically fit in commit messages, then maybe on an annotated tag or something?

> Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again.

... Is this actually easier than editing it yourself?

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

#135

Post by erelong »

I've always found something like this funny: programmers writing detailed code for a computer to use but not detailed documentation for a human to use for using the code... there were frequently gaps in logic which they'd never allow with code itself

The form was usually something like "do x" where x was composed of "y + z" but how to do y or z wasn't explained

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

#137

Post by nunez »

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

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

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

#138

Post by socalgal2 »

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.

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.

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

#139

Post by nunez »

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 your job. So developers now write strong and extremely detailed documentation.

I wonder how tech writers feel about all of this.

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

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

#140

Post by pixl97 »

socalgal2 wrote: post #138
vitally3643 wrote: post #129

Earlier quoted context omitted.

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.

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.

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.

Post reply on HN