So this is somewhere between code comments and Confluence pages. Seeing as even comments can get stale, how accurate do these docs stay? The added focus on "why" instead of "what" seems more resistant to cruft.
A much bigger issue is comments that are a few lines (or a few tens of lines) away from some piece of what they're talking about. Then, they suffer from exactly the same issue as documentation anywhere, inside the repo or out: something drew the developers attention to the code that needed to be changed, but then there was no reason they should have known to look in this particular other location for text talking about what they changed. That's not the programmer's fault, unless we want our programmers to take the time to review every piece of documentation for anything that might need to be changed. I'd guess there are some contexts where that's appropriate, but I haven't ever worked in one.
Alternatively, we could have it be someone's job to own the docs, continually run over them and make sure they still apply, and stay abreast of PRs as they merge. I haven't seen that tried - it might be valuable if it was a role someone wanted.
What I've been trying is adding cross-references to my code, so that something can always be visible on the line or a neighboring line that notes that there's something relevant in another place. This is then checked in CI for integrity, and references that appear in the diff have their referents surfaced on the PR for the benefit of the reviewer. So far the links are pretty sparse, but have already been somewhat valuable. I intend to piggyback on the same system as I introduce ADRs.
I'd like to release the above tooling as F/OSS but really the trickiest parts are CI integration. The check is literally piping git diff to grep, looking for things of the form ^^{some label} and finding the associated @@{some label}. I decorate the PR on github with annotations through the Git Checks API.