How do you keep documentation up to date with AI generated code?

5 pointsby ghosts_9 comments

Comments

Hacker News

have an ai workflow man it’s mid 2026.

any time ai does any work, it ensures the ADRs are up to date.

it is part of the execution workflow.

maintain the todos which are a record of work that was done. ADRs have the latest current documentation.

by moomoo11

Honestly same way I did before, checking periodically. There's a real challenge though: I'm getting less and less knowledgeable about the details of my own code, so it's hard to fact-check everything all the time.

Anyway, for now we're assisting to either outdated Docs (Coding Agents often don't even look at them), or to over-bloated ones (the slop is not just in the code). We should probably still find a balance between human readable docs (e.g. README.md) and LLM-tailored ones (e.g. llms.txt)

by rstagi

I pr and do regression test

by jsabess24

From my observations - by accumulating technical debt faster than US and EU financial combined.

If someone asks about the internals of the projects it is - you want the truth, you can't handle the truth.

by ReptileMan

The documentation lives alongside the code and is changed at the same time.

by trio8453

If you want do it right:

1. Update the documentation first, to describe the desired / expected behaviour.

2. Followed by the code changes that implement the documented behaviour.

PRs: for any behaviour change, feature addition etc: patch must include corresponding documentation updates. If not: reject.

Iirc that was (still is?) OpenBSD's approach to keeping docs up-to-date.

by RetroTechie

replace documentation for an agent/chatbot accessing a RAG with the collection of requirements/design docs plus the code repository. I have been doing a POC at my day job and it works surprisingly well even with SLMs ( Gemma3 4B, i smy current favourite )

by slipwalker

The same entity that generates the code generates the documentation. If you have 75% of your code generated by AI, then 75% should be documented by AI.

by segmondy

with local AI, I can set a for loop that runs nightly on any files updated the prior day and point it to a <file>.md right next to it and just have it revise it. You canimagine any number of loops like this.

Obviously if you're using cloud solutions who both generate garbage faster and cost money per garbage, this doesn't work.

by cyanydeez

Join the discussion

Write your take first — we'll ask for email only when you're ready to publish.

Hacker News
have an ai workflow man it’s mid 2026.
any time ai does any work, it ensures the ADRs are up to date.
it is part of the execution workflow.
maintain the todos which are a record of work that was done. ADRs have the latest current documentation.
by moomoo11
Honestly same way I did before, checking periodically. There's a real challenge though: I'm getting less and less knowledgeable about the details of my own code, so it's hard to fact-check everything all the time.
Anyway, for now we're assisting to either outdated Docs (Coding Agents often don't even look at them), or to over-bloated ones (the slop is not just in the code). We should probably still find a balance between human readable docs (e.g. README.md) and LLM-tailored ones (e.g. llms.txt)
by rstagi
I pr and do regression test
by jsabess24
From my observations - by accumulating technical debt faster than US and EU financial combined.
If someone asks about the internals of the projects it is - you want the truth, you can't handle the truth.
by ReptileMan
The documentation lives alongside the code and is changed at the same time.
by trio8453
If you want do it right:
1. Update the documentation first, to describe the desired / expected behaviour.
2. Followed by the code changes that implement the documented behaviour.
PRs: for any behaviour change, feature addition etc: patch must include corresponding documentation updates. If not: reject.
Iirc that was (still is?) OpenBSD's approach to keeping docs up-to-date.
by RetroTechie
replace documentation for an agent/chatbot accessing a RAG with the collection of requirements/design docs plus the code repository. I have been doing a POC at my day job and it works surprisingly well even with SLMs ( Gemma3 4B, i smy current favourite )
by slipwalker
The same entity that generates the code generates the documentation. If you have 75% of your code generated by AI, then 75% should be documented by AI.
by segmondy
with local AI, I can set a for loop that runs nightly on any files updated the prior day and point it to a <file>.md right next to it and just have it revise it. You canimagine any number of loops like this.
Obviously if you're using cloud solutions who both generate garbage faster and cost money per garbage, this doesn't work.
by cyanydeez