Programmers will document for Claude, but not for each other • Hacker News Board

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

#31

Post by onlyrealcuzzo » Fri, Jun 05, 2026, 1:45 PM UTC

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.

For me, the primary purpose of documentation is to help myself in the future.

I don't view it as something I'm writing for someone else anymore.

Ultimately, I think that's helped me write better documentation.

Writing for an imaginary audience is typically harder than writing for a concrete one, and things you might think "someone else" might need to know - they either 1) don't, or if they do 2) won't read your docs anyway, most of the time.

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

#32

Post by samuelknight » Fri, Jun 05, 2026, 1:47 PM UTC

I learned a long time ago to avoid writing long emails because people don't read them. LLMs are quite the opposite, and will have 'attention' for every word you prompt it with.

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

#33

Post by maxpow3r » Fri, Jun 05, 2026, 1:49 PM UTC

I get claude to write a context.md for any github project i'm working on. It helps keep my context up to date, or else claude keeps telling me to build things I've already built.

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

#34

Post by dfxm12 » Fri, Jun 05, 2026, 1:51 PM UTC

If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help.

LOL. It didn't even cross the author's mind to consider reading the notes himself to decide if they make sense.

AI is sending us down a path of anti-social behavior. It will be bad for us, of course, but AI is only as good as it is because it was able to be trained on info from github, stack overflow, etc. Without socializing interesting info, humans and AI will both suffer.

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

#35

Post by brap » Fri, Jun 05, 2026, 1:53 PM UTC

It’s all about the incentives.

Unfortunately, companies often measure developers by their own PRs.

An unfortunate outcome of this is that writing docs for other developers isn’t really incentivized properly (and with stack ranking, you might even say it’s disincentivized). Writing docs for Claude, however…

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

#36

Post by jillesvangurp » Fri, Jun 05, 2026, 1:53 PM UTC

A lot of developer documentation is effectively write only. It gets written, often at great cost. But it doesn't get read a lot. It doesn't get a lot of feedback. It's typically out of date. And the lack of documentation is not really blocking anything important anyway.

If you are ever on a project where somebody goes "Somebody should write some documentation for X", you should counter it with "Great idea, get on it!". Mostly nothing will happen. It's rather thankless work. Some people are more proactive on this.

I actually tend to write documentation for myself. Because I'm old and wise enough to realize that if I come back to a project in two years, I will have forgotten most that I would need to get back up to speed quickly.

With agentic coding tools, it's different. The documentation helps. And it gets added to even if you don't ask for it. Which is nice. And you can get a lot of documentation added with a few simple prompts. Which makes it cheap and easy to generate.

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

#37

Post by seanwilson » Fri, Jun 05, 2026, 1:53 PM UTC

> I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.

Similar for adding static type checking, which makes it easier for AI and coworkers to understand the code, catch mistakes, and to refactor. And now there's coders willing to add static type checking to help AI but didn't see the benefit before for some reason.

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

#38

Post by pixel_popping » Fri, Jun 05, 2026, 1:55 PM UTC

Because there will not be any point of explaining for humans, it has to be explained so AI have all the context necessary to re-explain to a human, adapted exactly to match current skill/personality and so-on.

I used to write extensive docs, now I solely write docs (I mean, the typical automated model Zoo do it for me) so AI know what to do later. Even inside the team, we don't really explain (except very high level concepts) anything for onboarding because the onboarding is directly on the harness, the file structure of a repo isn't even really checked anymore (probably no point, soon enough) as most people will end-up entirely on a chatbot anyway, it's start to be hard for me to even justify going out of our own internal harness windows (I have 16 to 32 of them open with 8 monitors).

I genuinely think a massive wave of depression will hit "tech workers" when they might realize that all our greatness (programming, arguing, planning...) will just be to prompt all day long and we will just be all in a "chatbot" in the end.

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

#39

Post by dbvn » Fri, Jun 05, 2026, 1:55 PM UTC

pixel_popping wrote: post #38

Because there will not be any point of explaining for humans, it has to be explained so AI have all the context necessary to re-explain to a human, adapted exactly to match current skill/personality and so-on. I used to write extensive docs, now I solely write docs (I mean, the typical automated model Zoo do it for me) so AI know what to do later. Even inside the team, we don't really explain (except very high level…

[flagged]

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

#40

Post by arjie » Fri, Jun 05, 2026, 1:55 PM UTC

Truth be told, I wrote docs for other programmers but now I have Claude Code write docs for itself but if you looked you might conclude that I wrote docs for Claude.