I've always tried, but usually work demands make it difficult to stop and finish. At least these days I can hand off documenting to an LLM. If anything, I have to tell it to back off a little to make it more readable for human eyes.
Programmers will document for Claude, but not for each other
81–90 of 166 posts
Re: Programmers will document for Claude, but not for each other
#82Earlier 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"
Sometimes you get lucky and it both looks up the documentation and then ignores it and makes stuff up.
Re: Programmers will document for Claude, but not for each other
#83I'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.
Always fun collaborating with someone on a project and having them surprised you actually read their documentation and checked out their code instead of expecting them to explain everything from the ground up.
Re: Programmers will document for Claude, but not for each other
#84I have a project where I asked the coding agent to write a design doc for each new feature. It now has 80 or so design docs, which aren’t kept up to date, so it’s a historical reference that we don’t go back to in practice. At some point I will probably delete them.
In a different project, I instead have it maintain a project overview and a couple other docs, and we delete plan.md once the work is done and the docs updated. I like that better.
Re: Programmers will document for Claude, but not for each other
#85Programmers 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.
the key to avoiding slop in this context is to have it write inline documentation (e.g. jsdoc), so that you can quickly review if it matches the required implementation/interface
Re: Programmers will document for Claude, but not for each other
#86Earlier 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... )
One of the clients I’m consulting with has one of the best cloud onboarding docs I’ve ever seen. Lays out exactly the services supported. Who does what pieces. What is self service. They break out latency differences between the cloud environments and on-premises. A serious amount of good work that’s incredibly useful working within their system. I use it frequently. Their head of cloud engineering has a permanent “away” message on Teams pleading with people to check the cloud docs first instead of just asking him directly. I would be frustrated too.
Re: Programmers will document for Claude, but not for each other
#87[flagged]
Re: Programmers will document for Claude, but not for each other
#88Some people like to brag about how productive they have become with AI, but I see them spending a few hours a week adjusting which model to use, trying the new shiny harness or writing Claude skills. Are you really more productive if instead of coding you are spending your time tweaking the AI to do what you want?
That's just what the people that liked to put a lot of effort into customizing their IDEs or WMs have moved to.
Re: Programmers will document for Claude, but not for each other
#89Generating tonnes of documentation is easy, but it can easily get outdated and so much that no one would read it. Ideally, code should be the single source of truth. Documentation should be generated dynamically and upon request to not go stale. The amount of detail and how far to dig in should be up to the end user.
Re: Programmers will document for Claude, but not for each other
#90I'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 have a pretty decent readme on all projects, and a /docs folder for key areas that need specific instruction on complex ones.
My boss was looking at them, but even the simple ones he was pointing claude at it and asked it to make a document explaining it. Then he'd send me the document and ask me to check if it was accurate. I added a line to the last page "this is an ai summary and may contain mistakes. Use the project readme for validated information" and told him it was grand.