Oct 6, 2026, 3:35 PMClaude docs are worse than no docs >_<
- Oct 6, 2026, 3:35 PM
Replies
Constantly bewailingRosaCtrl@vivaldi.netOct 6, 2026, 3:36 PM@robrix I don’t know how to explain this to my colleagues. Could you do it for me?
Oct 6, 2026, 4:01 PM@RosaCtrl @robrix "we have docs. unlimited docs, but no docs"
Essentially the presence of AI generated documentation disincentives other people from starting to write docs because they already exist. However, AI documentation is often written such that other LLM bots have an understanding of the project when the operator instructs the bot to read it and give to the operator the info they want to have.
In short, you need an LLM in order to read LLM docs
- Constantly bewailingRosaCtrl@vivaldi.netOct 6, 2026, 4:11 PM
- Oct 6, 2026, 4:16 PM
@RosaCtrl @robrix tbf that part was mostly conjecture considering I don't have much experience with LLMs, and thought that was the only reason that could remotely justify the existence of LLM-generated documentation. But if even LLMs can't make sense of it that's all the more damning
Still though, the existence of documentation puts somewhat of a damper on the need for documentation to be created, so I will stand by that point still
- Constantly bewailingRosaCtrl@vivaldi.netOct 6, 2026, 4:24 PM
@crazazy @robrix yeah, I agree with that point. It’s exactly what’s happening. But just today at work I had a case of “the LLM said that according to the spect this is necessary” and the person that committed the spec but clearly didn’t write it said “oh no, that’s wrong, Claude probably put something on the doc while debugging” 😑
Cassandrichdalias@hachyderm.ioOct 6, 2026, 5:15 PM- Oct 6, 2026, 9:35 PM
@RosaCtrl I mean, maybe? The text it generates—docs mainly, but also names—is an impediment to understanding much more significant than simply reading the code (which is also generally a slog that I don’t recommend). Worse yet, you can’t ask what it was thinking (if someone else ran the session, anyway) and insist it come up with something better. Maybe worst of all, it disincentivizes someone who understands the system from writing better docs because hey there are docs already.
I’d also point to the terrible abstractions it comes up with as a significant part of the problem. On the one hand we have the hardest problem in CS being naming things, and so the names are meaningless; on the other hand we have the hardest problem in CS being naming things, and so the things it sees fit to name aren’t the meaningful concepts.
Give me algebras or give me death.
RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 4:53 PM@robrix Doxygen is right there!
- Cassandrichdalias@hachyderm.ioOct 6, 2026, 5:13 PM
@RethinkJeff @robrix "Docs" that are just a list of API interfaces and their signatures are not docs either. They're redundant expression of something already in the code. Docs explain actual contracts and usage.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 5:23 PM
- Cassandrichdalias@hachyderm.ioOct 6, 2026, 5:30 PM
@RethinkJeff @robrix Yes, but then it's not doxygen making your docs, it's just writing your docs interspersed with the code in comments doxygen can parse. 🤷 You still have to actually write docs.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 5:37 PM
- Cassandrichdalias@hachyderm.ioOct 6, 2026, 5:55 PM
@RethinkJeff @robrix The original topic of this thread was specifically people *not doing that work* and having some clod fake it.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 6:00 PM
@dalias @robrix IMO there's a difference between writing the docs and writing the comments that those docs are based on; I've seen a lot of words written about "self documenting code" that really isn't, so this seems like a case of different experiences talking past each other T_T because I've seen a lot of people treating the two things as separate processes.
Jonathan Polleythe_other_jon@mastodon.socialOct 6, 2026, 10:57 PM@dalias @RethinkJeff @robrix IMO, Doxygen is almost, but not quite, better than nothing. People think that they are putting good documentation in the code, but they are putting in the same old crap just in Doxygen format.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 10:58 PM
@the_other_jon @dalias @robrix Those people weren't going to write good docs anyway. This is like complaining that people will throw hammers at nails expecting them to bind boards.
- Jonathan Polleythe_other_jon@mastodon.socialOct 6, 2026, 11:28 PM
@RethinkJeff @dalias @robrix I would love to see some code that generates useable documentation via Doxygen. I comment the crap out of my code, and I doubt it would make an acceptable document.
- Cassandrichdalias@hachyderm.ioOct 6, 2026, 11:46 PM
@the_other_jon @RethinkJeff @robrix Without intentionally writing comments intended as external documentation, I would not expect comments to magically yield it. Comments are normally documenting non-obvious internal things not external interface surface.
Natanox 🇺🇦🇵🇸Natanox@chaos.socialOct 7, 2026, 10:33 AM@dalias @RethinkJeff @robrix The most ironic thing about most of those docs generators is that they're pretty useful to determine functionality… for LLMs. But way less so for humans, usually.
The very brief descriptions in the code just aren't enough for static generators to extrapolate enough digestable information for anyone who *isn't* already knowledgeable in the very thing it describes, thereby it often lacks example implementations. It *needs* a human to work on good, useful docs.
- RethinkJeffRethinkJeff@mastodon.socialOct 7, 2026, 5:09 PM
- Oct 6, 2026, 9:30 PM
@RethinkJeff I think you’ve missed my point.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 9:35 PM
@robrix They think they're getting documentation for free, when they could already be getting it for free by commenting their code.
- Oct 6, 2026, 9:39 PM
@RethinkJeff ah, in fact I was missing your point. Yes, that’s a thing too.
I was thinking of code Claude itself wrote, tho, and I have a harder time blaming people for not wanting to wade in and understand what the agent did well enough to document it effectively since they’d then be confronted with the need to justify its shitty abstractions, and, well.
- RethinkJeffRethinkJeff@mastodon.socialOct 6, 2026, 10:00 PM
@robrix Ah, yes, one of the agencies I've done work for before is hiring for someone to do code interaction stuff with AI generated code and woooooooo no thank you an LLM is not going to produce reflection ready code.
Dan Deandandean@indieweb.socialOct 6, 2026, 5:11 PM@robrix they really are. They're like nonsensical vague fan fiction lacking any real sense of purpose.