> 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.
Today I had AI do a design doc cleanup and conciseness sweep on a vibe code project I have.
It removed ~50% totaling 30k words! So annoying how everything I discuss with AI gets documented in 10 the length, and then every subsequent decision is documented in 5 places.
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.
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.
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.
Sublime was/is still the best, unfortunately had to finally abandon it due to lack of first-class agent support. Hard to find something that emphasizes core text editing first and that doesn't constantly have some new update to apply on start that may break or change something.
That's crazy. I did a Notes migration to a custom Java/Red Hat platform 20 years ago, even at that time it was like "can't believe these guys are on Lotus Notes". I remember Howard Stern used to reference LN on his radio show in the early 90s.
> Call me a gatekeeper if you want but, we ended up with a lot of people that just can't do the job.
The vast majority! I think I've come across 1 or 2 competent engineers in 20+ years. It's a miracle that software works, ever. Increasingly, it doesn't.
> And more directly, I believe good software engineering is really hard.
It really is, if there's one sentiment that's remained consistent in me over time it's awe at how harsh of a mistress software is. As good as coding agents are, it still routinely dismantles them in astonishing ways. It's like complexity is the natural state to which all systems want to settle.
> "Why am I paying a consultant for something AI can do in 15 minutes?"
Tech consulting takes all kinds of forms. I've been doing it for a while. A lot of clients aren't thinking about time spent. A lot of clients have an in-house team that simply can't achieve something at all. Can't figure out how to do automated deployments, can't figure out their server OOM errors, can't figure out why a SQL query is slow. There is a huge swath of simply incapable teams. That's a whole class of opportunity potentially wiped out, I say potentially only because a lot of teams are so incapable that they still don't realize you can use an LLM to solve those kinds of problems.
And yes, every consultant loves to think they're getting paid for value, not time. Try telling a potential client that you're so much more skilled than their team, that you will finish the "200 hours" project in a single weekend, and that you would still like to bill 200 x market rate for it. Unless they are incredibly savvy, they will balk. If they are incredibly savvy, they probably don't have a shit eng team in the first place.
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.