upvote
Amen.

At work our documentation isn’t just getting littered with annoying jargon. It isn’t just all the hallucinations, either. (Since when has documentation ever been 100% trustworthy?) It’s that it’s so poorly written and structured that it’s becoming borderline incomprehensible.

My company is currently considering making, “Why should I bother to read something you didn’t bother to write?” an official policy because even the executives are starting to burn out on all the time they have to spend wading through slop.

reply
I wish my company would do this. A coworker pulled an all nighter before a vacation and just left me with a million line claude summary of their work then just fucked off. The message was two-part due to size and lacked basic stuff like, "how to run".

He's going to be annoyed that none of that work was used. But the reality is, at least 75% of claude generated text is pointless.

reply
Somewhat off topic but every time I've experienced this sort of thing it was management's fault. If an engineer needs to pull an all nighter and hand off a pile of garbage then someone in management fucked up. If they can't see this scenario happening a mile away then they aren't paying attention.

It's easy to blame the engineer, but all too often they don't deserve it.

Sorry that happened to you.

reply
If it wasn't worth your time writing, it isn't worth my time reading.
reply
Haven't done it, but letting an AI polish a manual first draft might be the best of both worlds?
reply
It tends not to improve things. Besides the generally bland and muddied style, and the low-fidelity reinterpretation of your points, they also have a habit of randomly deleting sentences that didn't spark joy for them but were actually important.

I've found them useful to review docs for factual consistency and potential sources of confusion, but the correct workflow from that point is IMO to correct the draft yourself and then say "better now?"

reply
When the LLM decides to drive-by rephrase me when making a functional change it drives me up the wall haha.

Woah woah woah human, you can't just say there are "far too many" pipes with similar names to abbreviate their labels, the most I'll allow you is a "large number".

reply
The "polish" is the worst part!
reply
This, a thousand times. As the ratio of code to human writing necessarily [1] goes up, they become not just smarter, but more precise and technical, which requires them to use more jargon. You could say they become more nerdy. Hence, text generated by these models will become more easily recognizable, at least by default, when not asking them to twist themselves into something else via prompting — which degrades intelligence. This is a good thing, in my book, given all the slop we already have to contend with.

Of course there will be models trained on much less code and technical writing, and they will create more natural sounding prose, but they will lack the deep intelligence of frontier models. Seems like a fair tradeoff.

[1] watch the first couple of minutes on this bycloud video on scaling training data mixtures: https://www.youtube.com/watch?v=aD93kfArOik

reply
[dead]
reply