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.
C compiler error authors say the same thing.
Programmers will document for Claude, but not for each other
151–160 of 166 posts
Re: Programmers will document for Claude, but not for each other
#152Yeah, 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.
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.
Re: Programmers will document for Claude, but not for each other
#153I'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.
I think it was Joel Spolsky's book "User Interface Design for Programmers" where one of his strong points was that nobody reads manuals. Documentation isn't any different.
And on the article's point (the title at least), I write stuff for LLM more freely because they will not care if what I have written is complete garbage. I can't do that in the documents I write for fellow humans. They will be read by them and carry more weight, and therefore require much more effort to write. With LLM, all I care about is providing enough context.
May be we just need to ingrain some of that thought process in our for-humans docs.
Re: Programmers will document for Claude, but not for each other
#154What I see in this thread is that WE HATE EACH OTHER SO FUCKING MUCH that we would rather see the world burn than spend another second interacting with our inferior coworkers. Only _my_ time and effort is important.
Re: Programmers will document for Claude, but not for each other
#155I'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 survivor bias though. If they read it and did the thing and never bothered you, you wouldn't notice that.
Yes and no. If people read the docs or performed good searches, the questions asked would primarily consist of underdocumented questions, or questions about relatively novel problems. You can still get a vibe for whether the docs are widely read that way.
Re: Programmers will document for Claude, but not for each other
#156Yeah, 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.
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.
Re: Programmers will document for Claude, but not for each other
#157It's because Claude RTFM.
Re: Programmers will document for Claude, but not for each other
#158I mean yea my take is that there's basically nothing that claude could benefit from that humans wont. So I see no reason to make claude-specific docs.
With that said, yes, the difference is I KNOW claude will read my docs, especially if I shove it into the context and therefore, I KNOW I'm getting ROI on that work.
As someone who has written docs for years I have spent too many hours writing docs that my colleagues proceed to just ignore and ask me to explain verbally. Its a culture thing if people don't have a natural instinct to read docs and a culture of documentation and asking others to read the docs INSTEAD of bothering the human.
Also, there may be something to the theory that people don't learn well from docs as tutorial. I find 10x faster return when I make a video for people or tutor them through something rather than sending them a link and asking them to read it. Often this is because good docs are disciplined and try to answer the one question they were asked. Which is great, untill you realize most are missing necessary background so now you're in a bind. Do you document foundations that are covered in other places? Or do you cover them in your own words making 10x more work for questionable value? Its not an easy question
Re: Programmers will document for Claude, but not for each other
#159People are selfish.
Document for agent: it makes less dumb mistakes. I go faster
Document for teammates: they might go faster and get stack ranked above me
Document for future engineers: does it impact my salary to skip that? No? Ok.
Re: Programmers will document for Claude, but not for each other
#160> 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.…
I understand the author wants to add it every time as a signature, and having claude do it doesn‘t fulfill the purpose