Documentation is one place where humans should have input. If an LLM can generate documentation, why would I want you to generate it when I can do so myself (probably with a better, newer model)?

I definitely want documentation that a project expert has reviewed. I've found LLMs are fantastic at writing documentation about how something works, but they have a nasty tendency to take guesses at WHY - you'll get occasional sentences like "This improves the efficiency of the system".

I don't want invented rationales for changes, I want to know the actual reason a developer decided that the code should work that way.

Exactly. Often this information is not actually present in the code itself which is exactly why I would want documentation in the first place, given that I can always read the code myself if needed.

That's great if those humans are around to have that input.

Not so much when you have a lot of code from 6 years ago, built around an obscure SDK, and you have to figure out how it works, and the documentation is both incredibly sparse and in Chinese.

If you want to have an LLM piece together and translate documentation, this seems fairly reasonable

Because it takes time and effort to write documentation.

If people __can__ actually read undocumented code with the help of LLMs, why do you need human-written documentation really?

It doesn't need to be written by a human only, but I think generating it once and distributing it with source code is more efficient. Developers can correct errors in the generated documentation, which then can be used by humans and LLMs.

Docs are a form of error correcting coding for code. Docs+code allows you to spot discrepancies and ask which one is the intended behavior.

I can read code without the help of LLMs, too. Human documentation tells me why the code was written.

I stumbled across a fun trick this week. After making some API changes, I had CC “write a note to the FE team with the changes”.

I then pasted this to another CC instance running the FE app, and it made the counter part.

Yes, I could have CC running against both repos and sometimes do, but I often run separate instances when tasks are complex.

Maybe documentation meant for other llms to ingest. Their documentation is like their code, it might work, but I don't want to have to be the one to read it.

Although of course if you don't vibe document but instead just use them as a tool, with significant human input, then yes go ahead.

Although with code it's implementing functions that don't exist yet and with documentation, it's describing functions that don't exist yet.