counterargument: I always hated writing docs and therefore most of thing that I done at my day job didn't had any and it made using it more difficult for others.
I was also burnt many times where some software docs said one thing and after many hours of debugging I found out that code does something different.
LLMs are so good at creating decent descriptions and keeping them up to date that I believe docs are the number one thing to use them for.
yes, you can tell human didn't write them, so what?
if they are correct I see no issue at all.
Indeed. Are you verifying that they are correct, or are you glancing at the output and seeing something that seems plausible enough and then not really scrutinizing? Because the latter is how LLMs often propagate errors: through humans choosing to trust the fancy predictive text engine, abdicating their own responsibility in the process.
As a consumer of an API, I would much rather have static types and nothing else than incorrect LLM-generated prosaic documentation.
> Can you provide examples in the wild of LLMs creating bad descriptions of code? Has it ever happened to you?
Yes. Docs it produces are generally very generic, like it could be the docs for anything, with project-specifics sprinkled in, and pieces that are definitely incorrect about how the code works.
> for some stuff we have to trust LLMs to be correct 99% of the time
The above post is an example of the LLM providing a bad description of the code. "Local first" with its default support being for OpenAI and Anthropic models... that makes it local... third?
Can you provide examples in the wild of LLMs creating good descriptions of code?
>Somehow I doubt at this point in time they can even fail at something so simple.
I think it depends on your expectations. Writing good documentation is not simple.
Good API documentation should explain how to combine the functions of the API to achieve specific goals. It should warn of incorrect assumptions and potential mistakes that might easily happen. It should explain how potentially problematic edge cases are handled.
And second, good API documentation should avoid committing to implementation details. Simply verbalising the code is the opposite of that. Where the function signatures do not formally and exhaustively define everything the API promises, documentation should fill in the gaps.
This happens to me all the time. I always ask claude to re-check the generated docs and test each example/snippet, sometimes more than once; more often than not, there are issues.
I guess the term "correct" is different for me. I shouldn't be able to nitpick comments out like that. Putting LLM's aside, they basically did not proof-read your own docs. Things like "No python required" are an obvious sign that you
1. Started talking about a project (you {found || built} in python), want to do it in Rust (because it's fast!) and then the LLM put that detail in the docs.
If they did not skim it out, then they did not read their own documentation. There was no love put into it.
Nonetheless, I totally get your point, and the docs are at least descriptive.
> LLMs are so good at creating decent descriptions and keeping them up to date
I totally agree! And now that CC auto-updates memories, it's much easier to keep track of changes. I'm also confident that you're the type of person to at least proof-read what it wrote, so I do not doubt your validity in your argument. It just sounds a lot different when you look at this project.
I was also burnt many times where some software docs said one thing and after many hours of debugging I found out that code does something different.
LLMs are so good at creating decent descriptions and keeping them up to date that I believe docs are the number one thing to use them for. yes, you can tell human didn't write them, so what? if they are correct I see no issue at all.