Programmers will document for Claude, but not for each other

cyanydeez

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.

dude250711

1. Claude's productivity is your productivity, but team's productivity is not your productivity. 2. Claude will actually read what is written (well parse for autocompletion, not actually "read", unless you are under AI-psychosis).

gonzalohm

Some 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?

freddieRidell

yeah, because claude will actually read the docs

ang_cire

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.

Pxtl

I've been noticing that too. "Hey, the normal documentation for our software of a crude API list describing what each command is and each of its parameters isn't good enough for the AI. We need to provide the AI with instructions on how to use the software to solve common problems" Uh, you needed to do that for humans too. You just didn't. There's a reason everybody scrolls to the bottom of man pages ASAP.

jfyi

I've never had this problem. The problem I have had is other developers expecting me to maintain documentation for their tools. To the point that they wage stupid inter office wars because they don't want to learn a command line utility with 20+ years of documentation itself.

jerf

Yes, I've already "abused" this a couple of times to get some docs written that we had needed for years but hadn't been written. All kinds of docs; code documentation, deployment documentation, overview documentation, architecture documentation. APIs that we kicked around as being useful for years are now actually on track to be written because we can't integrate non-existent APIs into MCP servers or skills. On the one hand, I also feel like "come on, couldn't we have done this earlier?" On the other hand... the costs of the docs have decreased. Simply firing a frontier model at your code base doesn't always produce perfect docs but it's a heck of a good start. I do recommend some tuning in the request, e.g. I like to explicitly ask the AI to document data flow rather than the usual list of "here's this component, here's this component, here's this component", but it's pretty easy. And the utility of docs is now much higher. I really just recently moved into the classical "architect" role and in some ways I'm glad it wasn't much sooner, because my GenX cynicism tells me that nobody ever reads the architecture docs . OK, OK, sure, technically nobody is a bit too strong. Sometimes, some particularly intrepid or conscientious souls surely read them at some point. But from my own experience I could count on being able to hand out API docs, structure docs, flow docs, and their primary utility was that when someone tried to deflect responsibility with "but but but they didn't provide any docs" they couldn't, because I had. People eventually learned to stop doing that because I always provided the docs because I saw that coming. And they made a great background on the shared screen as I had to walk someone through the entire thing in a meeting anyhow. They were more a really specialized meeting transcript than something I could provide in advance and expect much out of. But now, if nothing else, AI will read the documentation. I can tell people to pull it in, and while it doesn't mean all my problems go away, there is now a much cleaner path for me from "writing an architecture doc" -> "lines of code in somebody's repo" than there was pre-AI. My architecture docs are now somebody else's prompts. The utility of this sort of documentation skyrockets compared to the old days. So, when the costs decrease and the benefits increase, it isn't a surprise that suddenly, it's easier to get some of these things done that we "knew" we needed for a long time, but now with the new cost/benefit ratio can cross the action threshold.

jimberlage

Managers will document for employees. That’s maybe the better comparison.

loglog

It's not just documentation. Everything that makes programming easier is now suddenly valued, because wasting tokens is obviously worse than wasting your employees' time.

phplovesong

I have large doc file from a feature and everytime i tell claude to do something (read it) it consumes a shitton of tokens. Better to have small focused facts for ai instead.

empath75

Claude A) reads the documentation and B) needs the documentation C) can write the documentation quickly. None of which is true for your and your coworkers, at least not consistently.

kuboble

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 human. I just turn on my microphone, keep dictating whatever comes to my mind and I think might be relevant. After this is done I may or may not ask Claude to rephrase what I wrote before keeping it as memory. On the other hand people judge you for what and HOW you type. They complain about it. It's in my experience that people will generally judge a programmer much more for the quality of his outputs than the number of them. So if your target are other humans - it's better to have no docs than bad docs. For claude it's the other way around.

raincole

Because Claude actually reads what I wrote. Other programmers, not so much. I had an online art class right before Stable Diffusion came out. After SD workflow got well known among the art community, I asked the teacher what's the difference between AI image-gen and human artists. His answer (paraphrased): It's easier to make AI learn.

samuelknight

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.

maxpow3r

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.

dfxm12

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.

brap

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…

jillesvangurp

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.

seanwilson

> 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.