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

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

#51

Post by frizlab » Fri, Jun 05, 2026, 2:07 PM UTC

kuboble wrote: post #27

Claude never complains. In my experience the text for the Claude has only one requirement - the intent and meaning must be there. The text for Claude doesn't need structure. Doesn't need style. Doesn't need formatting. Doesn't need deeper thought. The only important thing is that it includes somewhere somehow the relevant bits of information. The quality of prose I throw at him is below what I would show to any other…

But the critique is good! I strive for feedback when I write docs. Usually they are just ignored though.

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

#52

Post by [deleted] » Fri, Jun 05, 2026, 2:09 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.

[deleted]

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

#53

Post by sumitkumar » Fri, Jun 05, 2026, 2:11 PM UTC

Documentation is worth it only if it is read. If your coworkers don't read/remember/respect the documentation process then people tend to not keep the docs up to date. Unless the docs are for users who you don't want to come to you at all for support.

Claude is a better reader. I have to just tell it to read the docs/specs sometimes.

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

#54

Post by rootsudo » Fri, Jun 05, 2026, 2:12 PM UTC

sumitkumar wrote: post #53

Documentation is worth it only if it is read. If your coworkers don't read/remember/respect the documentation process then people tend to not keep the docs up to date. Unless the docs are for users who you don't want to come to you at all for support. Claude is a better reader. I have to just tell it to read the docs/specs sometimes.

This is so true. I hate it. I document the same way for myself as I do with claude/codex and it's great it wasn't to much of a difference to be more verbose outside maximizing tokens.

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

#55

Post by semiinfinitely » Fri, Jun 05, 2026, 2:13 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.

Turns out all this time you were writing for AI to read!

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

#56

Post by duskdozer » Fri, Jun 05, 2026, 2:14 PM UTC

samuelknight wrote: post #32

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.

Ah, I had that realization too. Then I started writing short emails and they still didn't read them.

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

#57

Post by pixel_popping » Fri, Jun 05, 2026, 2:16 PM UTC

dbvn wrote: post #39

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]

What's funny?

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

#58

Post by [deleted] » Fri, Jun 05, 2026, 2:16 PM UTC

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.

[deleted]

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

#59

Post by rufo » Fri, Jun 05, 2026, 2:17 PM UTC

hilariously wrote: post #14

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.

Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case: 1. Immediate better output from the machine OR... 2. Being sidelined for career promotions because you spent so much time making sure documentation was accessible while everyone knows they can ask you instead of reading it, and you will answer.

re: #2: I'm in this description, and I am anguished by how much I do not like it.

(reference: https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-l...)

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

#60

Post by ModernMech » Fri, Jun 05, 2026, 2:19 PM UTC

bachmeier wrote: post #28

cyanydeez wrote: post #2

sure, but those documents are generally just as useless because they're 70% complete, 10% indirect and 20% wrong. Unstrutuced slop is no better at best, and much worse at worst.

> 70% complete, 10% indirect and 20% wrong I haven't had too much problem with information in summaries being wrong, but there have been times the LLM will miss the most important details. Then when you tell it, the response is "Nice catch!" or something like that.

The key thing that makes a summary valuable is it retains the most important details while being shorter. Missing those details makes the summary wrong.