[idop]

Indeed. I have never used an LLM to write. And coding agents are terrible at writing documentation, it's just bullet points with no context and unnecessary icons that are impossible to understand. There's no flow to the text, no actual reasoning (only confusing comments about changes made during the development that are absolutely irrelevant to the final work), and yet somehow too long.

The elephant in the room is that AI is allowing developers who previously half-assed their work to now quarter-ass it.

[jbstack]

"Please write me some documentation for this code. Don't just give me a list of bullet points. Make sure you include some context. Don't include any icons. Make sure the text flows well and that there's actual reasoning. Don't include comments about changes made during development that are irrelevant to the final work. Try to keep it concise while respecting these rules."

I think many of the criticisms of LLMs come from shallow use of it. People just say "write some documentation" and then aren't happy with the result. But in many cases, you can fix the things you don't like with more precise prompting. You can also iterate a few rounds to improve the output instead of just accepting the first answer. I'm not saying LLMs are flawless. Just that there's a middle ground between "the documentation it produced was terrible" and "the documentation it produced was exactly how I would have written it".

[fxwin]

Believe me, I've tried. By the time i get the documentation to be the way I want it, I am no longer faster than if i had just written it myself, with a much more annoying process along the way. Models have a place (e.g. for fixing formatting or filling out say sample json returns), but for almost anything actually core content related I still find them lacking.

[orwin]

But are you gaining a meaningful amount of time, and are your coworkers that thorough.

Honestly I just don't read documentation three of my coworkers put on anymore (33% of my team). I already spend way to much time fixing the small coding issues I find in their PRs to also read their tests and doc. It's not their fault, some of them are pretty new, the other always took time to understand stuff and their children de output always was below average in quality in general (their people/soft skills are great, and they have other qualities that balance the team).

[fastasucan]

Why not write it yourself?

[idop]

Sure, but that's part of my point. It gives a facade of attention to detail (on the part of the dev) where there was none.

[tahigichigi]

OP here. You're absolutely right!

Most people drop a one line prompt like "write amazing article on climate change. make no mistakes" and wonder why it's unreadable.

Just like writing manually, it's an iterative approach and you're not gonna get it right the first, second or third time. But over time you'll get how the model thinks.

The irony is that people talk about being lazy for using LLMs but they're too lazy to even write a detailed prompt.

[fxwin]

I have tried using them, both for technical documentation (Think Readme.md) and for more expository material (Think wiki articles), and bounced off of them pretty quickly. They're too verbose and focus on the wrong things for the former, where output is intended to get people up to speed quickly, and suffer from the things i mentioned above for the latter, causing me to have to rewrite a lot, causing more frustration than just writing it myself in the first place.

That's without even mentioning the personal advantages you get from distilling notes, structuring and writing things yourself, which you get even if nobody ever reads what you write.