unlike programmers, claude understands programmers.
You don't need a theory of mind to effectively manage or collaborate with a chatbot. You do for other humans.
Programmers will document for Claude, but not for each other
71–80 of 166 posts
Re: Programmers will document for Claude, but not for each other
#72Programmers aren't documenting for Claude. Claude is documenting for Claude. Programmers are, at best, reading the documentation Claude wrote for itself to ensure there are no glaring mistakes.
Re: Programmers will document for Claude, but not for each other
#73We 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 developme…
I get the feeling specifications documents are going to become the hot new programming language. I suspect, over time, we'll see special syntax and semantic conventions get published for specifications docs that result in the best chance for a coding agent to get the implementation right the first time and with minimal tokens.
Re: Programmers will document for Claude, but not for each other
#74I'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.
Very often that is a sign of poor UX, or that the documentation is in the wrong place.
Re: Programmers will document for Claude, but not for each other
#75Earlier quoted context omitted.
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... )
It's bad for us, but I imagine the tech writers feelings are even darker. They spent years being demonstrating how important good docs were, nobody in management cared, they were mostly laid off and discarded before there was even a credible replacement available.
Re: Programmers will document for Claude, but not for each other
#76Why make this about Claude? People are free to use any agentic coding LLM.
Documentation is firstly for yourself, secondly for your coworkers and/or users, and only last for AI. It is the art of writing and revising it that strengthens+questions+maintains one's understanding, so it doesn't make sense to have an AI write it.
Re: Programmers will document for Claude, but not for each other
#77Programmers aren't documenting for Claude. Claude is documenting for Claude. Programmers are, at best, reading the documentation Claude wrote for itself to ensure there are no glaring mistakes.
I came to this realization after seeing developers churn out 30 minute long reads of slop documentation. It's for the agent, and the human interface to it is through the agent. Over the last week the plans that Claude has been writing for issues have been largely a single massive unreadable paragraph of awkward sentences, but it's working, the implementations from it have been solid.
Re: Programmers will document for Claude, but not for each other
#78It's not just documentation. Everything that makes programming easier is now suddenly valued, because wasting tokens is obviously worse than wasting your employees' time.
Employees get paid either way, so weirdly that makes it less motivating. Costs aren't lower if you put more work into writing a good spec.
When you're paying piecework style, suddenly the work needed to write a good spec has a bottom-line payoff.
Re: Programmers will document for Claude, but not for each other
#79I'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.
If it helps, I have found the attitude that writing is mostly for the writer to be healthy in continuing the practice. And it largely tracks with how I feel I have had better understanding of things I have documented than those I have not.
Re: Programmers will document for Claude, but not for each other
#80Another blogger goes down. Of course programmers have documented important software for each other.
Claude emits garbage, so documentation will be garbage as well. It doesn't matter, because everything will be rewritten and tokenmaxxed anyway.
In other words, the blogger now has a job where Claude is foisted upon him and he toes the line.