recently I gave AI a task to configure a software and the software didn’t have any docs of how it works only the source code. the agent went through all the files and generated a summary of how it works and why it’s not working for my particular scenario and suggested edits to my docker-compose.yml file. I couldn’t believe it since the bug was very hard to find and it used headless firefox to find why it wasn’t working.
made me realize do we still need documentation of how a software work when a AI can easily explain it?
You must log in or register to comment.
Dawg get the fuck out of software and go get an MBA like you should’ve in the first place.
Money-chasers should stick to their own fucking lane. You’re fucking this up for those of us that actually like tech work. Fuck me.
I was in an incident at work for software written by AI, with docs written by AI. It lasted DAYs and AI nor the slopper who slopped it could get it working. The “docs” were horribly wrong. I finally fixed it and now im writing docs for it without AI.
AI is not “smart” or deterministic.
Putting my personal feelings about AI aside for a second …
Yes you absolutely 100% still need documentation.
- Documentation should be written by the same team writing the code, sometimes code can be left to interpretation and the original intent can help a lot.
- Documentation has a chain of custody. You can see who wrote it, when it changed and why.
- Documentation is deterministic, if you look something up you will always get the same exact response
- AI that answers your questions is built on documentation. AI cannot produce efficient documentation just based on code, it needs to be fed at least other documentation to know what it’s expected.
- Lastly AI is a grey field in the legal world. Everything in the enterprise world has to go thought risk/liability analysis. Let’s say AI gets something wrong in the docs and as a result you accidentally delete the prod DB. Who is liable? What happens with your insurance? can you be fired? Can the company sue you for damages?
Disclaimer: these are only my opinions and I’m not even a programmer. I support a dev-ops team in the field of cybersec.
I can’t wait for LLMs to go the way for crypto. I’m so tired of this bullshit.
There’s a lot of people here that clearly haven’t ever tried what you’re describing op (or maybe tried recent AI at all).
I have. I think it’s a totally valid question. Sometimes when I’m getting AI to do stuff it reads the docs and then tries stuff anyway and finds the docs are wrong.
I also often use AI to generate docs for undocumented things.
But I think it does still make sense to have docs for a few reasons:
- They show the intent explicitly, rather than having it inferred. Same reason anything explicit is better than implicit, e.g. static types.
- It spends fewer tokens to read docs than to constantly reverse engineer software.
- It’s also quicker.
- Sometimes you do still want to understand the thing…
bruh
Every time you use AI a puppy dies.
A new account making extraordinary claims about AI and phrasing it as a question? Again?
As much as I can’t stand AI fanatics, I think some of the anti-AI rhetoric (especially on Lemmy) can be just as dogmatic. OP didn’t make any “extraordinary” claims. LLM agents have actually gotten remarkably good at many programming tasks, in particular tracking down bugs, and some of the things they’re able to work out are genuinely impressive. At the end of the day it’s another tool, but it can be a powerful one in the right context.
That’s not to say anything about the environmental, social, and economic issues surrounding the tech and the industry. Obviously large companies are acting completely recklessly in all of those domains and I don’t intend to justify that aspect. That said, I think it’s disingenuous to frame OPs post as “making extraordinary claims” and it detracts from legitimate (and IMO mostly unimpeachable) arguments against AI.
Removed by mod
Good point, I guess I rescind my argument.
Removed by mod
This is not an extraordinary claim if you’ve used a good LLM in the last, say, year.
That’s right, move those goalposts!
How did he move them?
“You’re not using the latest model”, “You’re holding it wrong”, etc…
It’s the same shit, different day.
I’m consistently told LLM generated code is the best thing since sliced bread, and people keep handing me “proof”, yet every time I open what they’ve handed me, I see a shit sandwich.
And as soon as I point that out, the goalposts are moved yet again, ad infinitum.
I think the effect you’re seeing is that different people have different levels of “good enough”, and also they work in different domains where AI became good enough at different times. E.g. for one-off web page design it’s been good enough for a long time.
I never said this for earlier models, because they did suck for things like Rust and SystemVerilog. Now they don’t.
I’d share some things I’ve vibe coded that work basically perfectly but they’re linked to me real name, but you could have a look at the Mold linker which was recently vibe-ported to Rust.
You do understand that this is a rapidly developing technology right? That it’s getting better weekly?
It’s clear you have no idea what you’re talking about. You can’t just bury your head in the sand and tell yourself that LLMs are still just “advanced autocomplete” anymore.
It’s clear you have no idea what you’re talking about. […] You do understand that this is a rapidly developing technology right? That it’s getting better weekly?
This is literally the retort that moves the goalposts.
You can’t just bury your head in the sand and tell yourself that LLMs are still just “advanced autocomplete” anymore.
I made no claim that LLMs haven’t changed, I make the claim that others are making claims that fall apart once examined.
The claims others make:
-
AI is amazing because now it can make this thing
-
Oh, the only reason doesn’t hold up to scrutiny this one time is because of {insert goal post moving here}.
Argument 1 falls apart when looking inside the product (i.e. the shit sandwich, the slop grenade, etc…).
Argument 2 is circular, so I’m not going to waste time on it.
But just for the sake of argument, lets say there’s some sudden release of a model tomorrow that runs one million times better than today’s best model and everyone only uses that model from now on. Will I still be handed a shit sandwich?
Yes.
Why?
Because the fact that I’m handed a shit sandwich isn’t influenced by how good the model is. It’s based on the fact that English is a terrible language for logic.
We discovered this in the 60s and 70s. Computer programming was too hard in the 50s and only getting harder, so everyone got together and tried to make a programming language out of English, that way everyone could do it. That’s literally how the Cobol language came to be. It was sold to everyone on the idea that anyone could create something with a fuzzy human readable language called English.
What did we learn? English is both a terrible programming language and a terrible specification language, Non-programmers (managers, general workers, etc…) fall prey to things like the xy problem, understanding gaps, intention gaps, etc… and so can’t end up with a new good product by giving orders. The scars of that delusion are still felt in our banking system today. Every lesson learned by Non-programmers in the goal of getting a good program turns them lesson by lesson into programmers, and at that point you’re just programming by hand anyway.
The same lessons were rediscovered in the 80s by people trying to program by spreadsheets and GUI-only app builders, the 2010s with the no code movement, it’s currently being rediscovered in the 2020s with LLMs, and it’ll be rediscovered again by a new generation in the 2040s once those with the experience and learned wisdom of last time retire out of the industry and the few remaining are outnumbered and dismissed as religious zealots.
Literally not moving the goalposts.
-
Wut?
I responded in the other comment
It’s really horrifying to see the cult propagate to lemmy, out of all places.
Go back to your closet with your blockchain and nft bros.
At some point you have to try it to see whether maybe it’s you that is wrong.
(And when I say “it” I mean Astra/Opus 5.5. IMO earlier models did not quite live up to the hype.)
In what universe does “LLMs are good at some programming tasks now” make someone part of a pro-AI cult? This is the exact kind of black-and-white dogma you seem to be upset about.
Because LLMs are good at nothing other than maximizing the profit that “AI” companies make off the back of gullible sheep. That’s their actual goal and the only thing they succeed at.
A slop machine is not good at any task other than producing slop. A broken clock showing the correct time twice per day doesn’t mean that it is working, and we’re not lacking studies that prove that no, LLMs are not a tool that can be used for anything useful or worth the costs.
This is just… objectively false. LLMs aren’t miracle machines, but they’re capable of performing certain tasks well and can be very useful in the right context.
I’m sure that you’ll paint me as an AI shill incapable of independent thought for admitting this, but since starting a new job this year I’ve used LLMs most every day for software development tasks. It’s excellent at catching mistakes and tracking down root causes that it would take me sometimes several times longer to find manually. The latter literally saves me days to weeks in the context of broad refactors, where there are hundreds or thousands of opportunities for me to make a typo or miss a case.
And no, I’m not blindly pushing “slop” into the product. I consider myself good at what I do and I’m capable of vetting every line of work that it does and recognizing when it’s low-quality or misses the mark in some way.
Again, I’m not claiming they’re miracle machines. They’re subject to their own limitations and certainly aren’t suited to every task. But to claim they can’t be used for “anything useful” is completely disconnected from reality and, at its core, simply dogmatic.
“I believed in this product enough to use it everyday, and it led to me believing in this product” has quite the sect-like thought process resonating through it.
You believed that LLMs work, and you used them. And then, your experience as a “believer” is your reason to believe in them. There’s no core to it, no critical thinking, just self-maintaining beliefs.
It’s like religious people believing in miracles because they are religious, then saying that the miracles are the proof that their beliefs are true. That’s just circular logic.
And with LLMs that have been shown to erode critical thinking and cause psychosis, that is even more meaningful.
You believe that you can vet every line of work, and you might believe that you do. You believe that the LLMs make things faster, you believe that the result isn’t worthless, you believe that it is sometimes less error-prone than you (which is worrying in itself), etc. And that would be fine, if these beliefs didn’t have the incredibly huge amount of very bad consequences that LLMs have.
This is so divorced from reality that it’s frankly insulting. I “believe” in it because I’ve gotten good empirical results, not because I put blind faith into it. On the contrary, I’m extremely skeptical of anything it produces. And yes, I can vet every line of code. I’m skilled at what I do. I know how to do code review, whether it’s written by a human or a machine. I can judge code and architectural quality or whether the root cause it landed on is accurate.
More often than not, the work done by the LLM is effectively the same as what I would have ended up with anyway, except instead of taking an hour or two to step through all the layers of the application to find the root cause I get an answer in about 5 or 10 minutes. How do I know it’s not slop? Because I can read the code it references, understand the exact reason that the bug occurs, and fix it myself and watch the bug disappear.
I’ve been on the internet long enough that not a whole lot tends to get under my skin, but you asserting that I lack the ability for critical thought and just blindly trust the LLM output because I’m incompetent and don’t know what I’m doing is beyond insulting. The irony is that you’re the one applying your preconception to apparently anyone who disagrees with your dogmatic view. It’s called post hoc rationalization: AI is obviously useless; therefore anyone claiming it has utility is doing so on blind faith and isn’t applying critical thought because otherwise they couldn’t possibly have come to that conclusion. I would suggest you reflect on the way that you’ve approached this dialogue, but the level of arrogance on display here tells me that you almost certainly won’t.
Also, because I expect you to point and say that this is evidence that I’m some rabid AI zealot frothing at the mouth to defend the tech: I have no absolutely love for AI companies and I don’t have a serious stake in the actual tech beyond it being a part of my workflow (societal/economic/environmental concerns notwithstanding). I don’t care about it any more than I do the literal physical hammer in my toolbox. I just think you’re a condescending asshole for telling me that actually, I only think it’s hammering the nails in because I’ve put my faith in the hammer and I’m too oblivious to tell otherwise.
I am sorry but I couldn’t resist AI. was avoiding it for very long time but it’s actually good. specially for tedious task which I have to do. now I can focus on the fun part :)
More like couldn’t resist obvious astroturfing
If that isn’t the most whitewashing AI comment I’ve ever seen…
noone is saying AI is ethical.
So why are you using it? Why are you trying to whitewash something unethical?
Why do you drive a car?
Because I currently live in a country built around the car as the focal point for all urban planning, to the detriment of all of us. I also drive as little as possible, walk to work, etc. I’m not over the top enthusiastic about “how amazing it is to be forced to drive a car for literally everything” like you seem to be about AI.
It’s one thing to be excited about AI from the getgo. It’s another, seemingly incredibly disingenuous thing to say “I tried but just couldn’t resist AI now look at how amazing it is there are zero downsides!”. That right there is basically what you’ve said, and comes across solely as a statement to try to astroturf public opinion online.
I haven’t said anything but… Do have you ever taken a flight instead of walking?
You must accept at some point that really fast and convenient wins, despite some environmental concerns (which are not even that bad really).
made me realize do we still need documentation of how a software work when a AI can easily explain it?
I’ll respond for the sake of argument, but to put it bluntly: there are no stupid questions, just questions phrased stupidly.
Documentation comes in many formats. There’s prose documentation split into articles and chapters, there’s video documentation, inline documentation for code, tutorials, training, and so on. Most things are documented several ways. This is because people learn things differently from each other.
To remove documentation entirely and rely on only LLMs to document removes all of the ways that people might learn and narrows it down to only one form of documentation. Even if we ignore how fallible LLMs can be, having documentation in only a single format limits learning only to those who learn effectively through that format.
In other words, relying only on LLMs for documentation discards all of the millenia of teaching strategies learned throughout the course of human history and puts it in the hands of a stochastic magic box that is incapable of recreating those strategies.
That makes sense! Different people learn in different way so we need different people’s words on the same topic to have diverse view on subject.
Good point
Yes cause understanding software is important even if you use AI.
And even if you want to go full vibe code and never look at anything yourself the AI does need documentation, compare the performance of an agent on a large project with and without an AGENTS.md, the difference is massive. Without the agent usually does figure it out, but it spends a ton of tokens searching.
but it spends a ton of tokens searching.
I can see that could be an issue. also it’s nice to have a good idea of the codebase. good point
Heres a hot take: as a technology AI (whatever that may mean) can be genuinely useful. In the way it is implemented right now destroying the environment and rising the cost of everything I despise everything that it is. LLMs are the main culprit and the utterly idiotic decision to have one model know everything from embedded coding to ancient Babylonian history.
Neural networks and even specialized small LLMs that I run on decentralized systems are genuinely useful. I use open weight models that I run locally to help with implementing functions from stubs and even do documentation, which it truly is not bad at.
I don’t hate the technology, I hate the greedy dystopian hyper capitalistic environment destroying way it is deployed in. And the way that it is trained by literally stealing the work of creative people.
You’re doomed. But do it anyway, more work for me later.
Move along. This is a bot, likely out of Eglind or any of the other AFBs that are running bot farms astro-turfing for AI
“Everyone who says something I don’t like is not human”
Gtfo fash
How often will an AI explain, with near 90% accuracy, an entire distributed system. Better yet, make it generate documentation for prime95 and see how quickly it melts.
for a complex and large projects, it might be less accurate. but most project I use daily aren’t that complex (besides browser and linux kernel ).
there were an even I went to and the speaker asked, “what things AI couldn’t make”. my answer was “entire cloud platform like AWS” he was speechless xD
