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

61–70 of 166 posts

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

#61

Post by christoff12 »

Macha wrote: post #26
scottlamb wrote: post #22

Earlier quoted context omitted.

When someone asks me a question that is or should be documented, I like to ask where they looked for it (link or search query). * Sometimes, this prompt is enough for them to find the answer. * Sometimes, they tell me a spot that makes sense to them, and I make it have the answer. (Maybe just by adding a cross-reference.) * If they refuse to look at the docs, I can't help them.

The answer has always been “I asked Bob and Bob half remembered you worked in it once”, without any attempt to look for info, in my experience :(

That's when you direct them to the docs.

People rag on StackOverflow for being mean, but it was a good training ground for developing habits that satisfy the social contract of professional spaces.

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

#62

Post by manmal »

We are now writing specs for important components and algorithms, and spend quite a bit of time aligning on them before implementing the production version. Those specs are often informed by vibed prototypes, but usually it’s also two or more people really thinking through an algorithm, and aligning with interfaces to the adjacent systems. They are usually very information dense.

I don’t believe spec driven development is a good idea though. The architecture should be made with intention as well, or I feel we‘d end up with whatever happens to be ranked highest in the latent space. But the specs are great to align cross platform teams behind shared concepts, and they are a good input to automatic reviews.

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

#64

Post by ben_w »

fer wrote: post #24
noufalibrahim wrote: post #18

Earlier quoted context omitted.

Yup. Claude will rtfm. Most humans won't.

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"

While they absolutely do fail as you say (though in my experience not by default), this failure mode is still a massive improvement over the frequent human case of guessing based on the function/class/property/argument names.

Now, a really good human collaborator who reads all the stuff and thinks carefully, that was still better than what I saw from AI models at the start of this year. But I've also worked with my share of idiots, and been one too.

I'm not going to get into if *current* models can or can't reliably do any particular thing to any particular standard; previously my comparison was the same conversations with regard to video game computer graphics in the 90s always being "photorealistic" when they really weren't*; now, I'm starting to feel such discussions have the same vibes as Tesla fans insisting that "FSD-{insert current version here} solves all the problems and is a real breakthrough and the Rototaxi will totes conquer the marketplace this time for real bro, just one more version bro", etc.

* https://archive.org/details/nextgen-issue-26

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

#66

Post by forshaper »

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.

At some point I started to include jokes in documentation to encourage people to read it. For the most part, this only entertained whoever the knowledge or project admin was.

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

#67

Post by [deleted] »

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.

[deleted]

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

#69

Post by triMichael »

kittikitti wrote: post #45

There was a growing consortium of developers who bought into the idea of "self-documenting code." They actually considered you incompetent for writing documentation and relegated this to roles they deemed inferior. I wonder what these types of developers think of this?

I'm one of those developers, and I think it makes sense to write documentation for Claude and I have no issues with that.

The point of self-documenting code isn't to get rid of the documentation. Instead, it's to integrate it into the code. This fixes the two biggest problems with documentation. First, that the code will often be updated and documentation left behind, making it useless. And second, that English and code are intertwined in the same document, making you constantly switch mental contexts of how you are reading. So no, I don't consider developers who write documentation to be inferior. If anything, I value documentation even more, and the purpose of self-documenting code is to make the documentation better, not get rid of it.

With Claude, the documentation you make for Claude is just fine as it doesn't run into any of the above two problems. The documentation isn't being left behind, because you add to it instead of the code. And it's not intertwined with code, because you are just writing English for Claude, you are not writing code in-between.

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

#70

Post by wolttam »

As a human, I'd rather just explore the code (which I tend to trust more than anything written beside it) myself.

The bot though- I don't want it to waste a bunch of tokens exploring nonsense. If I can write a few lines of text that will help it get straight to where I need it to go for 99% of work, that's a win.

It feels hand-holdy when done for the bot. I don't want to hold my follow human's hands.

Post reply on HN