4 ms·
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 icon
by idop 8mo ago
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.
- fxwin 8mo agoI 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.
- jbstack 8mo ago"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".
- idop 8mo agoSure, 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.
- fxwin 8mo agoBelieve 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.
- tahigichigi 8mo agoI guarantee if you give me your prompt and the output you got I can fix it and get you a 10x better output in less than 5 minutes. DM me on substack if you don't wanna post it here, I'm honestly happy to help wherever I can.
- fxwin 8mo agoI won't share work related stuff for obvious reasons, but feel free to post an example of some LLM generated (technical) article or report of yours (I also doubt you would be able to understand the subtle differences i take issue with in LLM output in 5 minutes in the first place)
- fastasucan 8mo agoWhy not write it yourself?
- orwin 8mo agoBut 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).