Comment by thr0w
2 days ago
> they ask Claude to write an explainer for exactly that slice
If their Claude is the same as our Claude, then this is a joke. Claude’s writing style is insidiously mind numbing. It takes constant pushing to get it to explain things in digestible English.
It also mixes important with unimportant information. It tends to think that a commit/bugfix is important and will happily list it together with important properties of the feature.
At least Opus 5.5 does that. Its writing is better than that if other models, though. I had other models explain stuff in an undigestable language, technically correct, but practically not what anything is about.
I hate it when it realizes something that was contextually obvious to me, and then treats it like a precious nugget of wisdom, including it in the README, the comments, and the commit message. Even worse when it’s a hypothetical situation. “Even if the raw chicken is bagged and refrigerated, we want to avoid a leaky bag.”
I believe this is a variant of it: I dislike how often it mentions stuff that's not there or relevant (anymore), just because it was referenced somewhere: "We use a double instead of a float there so that the addition will not overflow". Yeah, thanks, that was a bug 2 years ago, nobody cares that the line now does what it's supposed to do.
1 reply →
It's like it's trying to impress you with poetry in comment: "What the function does, it does well, and only just once"
Try having it explain something in “ISO Plain Language standard”. It made an enormous difference for me yesterday. The language will change from dense large paragraphs to simply-worded 2-3 sentence paragraphs. I was using gpt though.
Even getting it to write less obtuse English isn't enough IMO. It seems to have real issues with structuring documentation in a way that makes it easy to follow. Also it's a real demon for leaking its context as implicit assumptions into documentation.
They pretty much fixed that. Plus you can influence the writing style to some extent. I tell it to use full sentences and avoid assuming I already understand the code.
Another thing is that it's very good at creating diagrams (I think someone wrote a skill for it so maybe not by default). I usually find the diagrams are even more valuable than the text.
Honestly I was skeptical but you really can just point Claude at some code and ask it to make a markdown + SVG explainer and it will do a shockingly good job.
I'd still rather read human documentation, but even before AI almost nobody writes any - especially for internal code. And they certainly don't make great diagrams.
I’ve been using diagrams a lot lately. My team currently owns a wide surface area, so there is a lot of mental context churn as we bounce between parts of the system. HTML diagrams, or artifacts in the Claude desktop client, are super for helpful for bootstrapping/refreshing my mental model when starting a new project.
Your Claude Code terminal now renders Images, LaTeX, Charts & Diagrams Use this mod I created: https://github.com/razorback16/cc-intelligent-ui
v5.5 eliminated much of the impenetrable prose of earlier versions.
> v5.5
You don't still feel that mental friction when 5.5 responds with a wall of text and you drop into that first tedious sentence? I even had it generate a syntactically invalid English sentence the other day. It's still pretty bad.
It’s better, but still worse than OAI’s models in my experience
Or we’re just getting used to it.
The people who work at Claude seem to talk in claudlish, so I doubt they care.
If we as engineers didn't use similar terminology to describe any code not written by ourselves for the last few decades perhaps people would take it seriously.
Claude was trained on engineering wittering.
Fairly sure all LLMs were trained on ads and sales and marketing copy as there's probably 1000 times more of that on the internet.
[dead]
But the words are all right /s
If it was an exception only… but it is so common that I had to put ASD-STE100 into instructions to have precise answers.