[seanmcdirmid]

Is that really true though? Are people really not saving design documentation to the code repository along with the code? And is it really too much to ask in a prompt to make the LLM document aggressively? Do the LLMs you use complain about being asked to write lots of comments in their code? Is it a token cost thing? It seems ridiculous not to just start with #2 but I might be spoiled by not knowing how much my token usage costs.

[avidiax]

It requires real work to create good documentation and review it.

I've never worked in a place that requires that every commit update some documentation, but if you want to rebuild software based on the documentation, that's what it would take.

The best you could say is that the typical development process today tends to scatter documentation across commit descriptions, feature docs, design reviews, meeting notes, training materials, and source code comments.

To have a hands-off rewrite of a codebase with LLMS, you would need a level of documentation that allows a skilled human to do the rewrite without needing to talk to anyone else. I doubt that any project would have this unless it was required all along.

[seanmcdirmid]

It doesn’t though. You tell the LLM what to document up front, it can be some domain specific detail or whatever. You don’t need to carefully review it unless things go wrong. You do change propagation and change everything (tears, docs, code) in sync when some spec aspect changes, which involves a QA feedback loop, which judges the correctness of code and tests (because the LLM wrote the tests, they can be wrong). I guess you could add doc review steps as well if you knew what to look for generically, but I found it’s ok at writing docs that I haven’t needed to do this yet.

[pconstantine]

The only docs that explain what code does are a carbon copy of the code. I've saw that "no-code, write docs, write spec" movie so many times, and it always ends as a flop in the box office.