> I've taken to putting a link to the Confluence docs
Middle ground I've found on some projects: very detailed code/data-oriented notes are in markdown in the repo, tied to a PR. Those doc files may reference external items like confluence pages or specific tracking ticket/URLs that relate to the code at hand.
I was on a team that had everything in confluence, and everything was impossible to find. The closest I came to understanding it was the confluence docs were always initial plans, but were rarely updated. When updated, you wouldn't necessarily know if you needed to look through 5 versions to see earlier thinking, or which links to 'updates' confluence pages you needed to trawl through. It was as much a problem of a growing set of contributors and growing departments than anything else, but there was a new 'direction' every 6-9 months (when new folks would come in) and "this worked at my old company" so they'd document stuff however they wanted.
No one on the dev team bothered to ever look there for anything, because it was simply pointless. Few people ever looked at it for anything more than "recent updates" to see what's changed in the last 2-3 weeks. Discoverability on the size of that project (and this is 'only' 5 years old ~80 people) was just useless.
A handful of folks did keep 'onboarding' stuff relatively up to date, but it was less than a year old at that point. I suspect that if those folks moved on, those docs may slowly rot.
On the whole, keep written docs both updated and useful and findable to a growing number of people with disparate needs and different contexts and backgrounds... it's a lot harder than it might seem when first considering it. Even if you have the people on a team with the aptitude for it, it's usually low priority in every work cycle, and the first casualty when trying to hit deadlines.