Confluence is where documentation goes to die.
At my old work I usually left a search going from the root network folder over the weekend, scanning for some keywords, when I needed a doc none knew where it was or if it existed at all.
There was a parallel documentation system from IBM that didn't work, where the canonical docs should be. But you more or less had to know the document ID to query it. So most documents were also in the network folders spread out between hundred project folders and meeting folders.
Because I do not see business documentation evolving with code. And depending on what the code does, business documentation could be much more important than technical documentation.
Some departments do stupid things like duplicating information. We use confluence to describe the requirements, the concepts, then point to the right locations.
Take IPs, some departments have pages and pages with the same IP, subnet, etc in
It's like:
cat $DOCS > /dev/null
rm $DOCS
Docs exist for people other than those that wrote them. The people that wrote them don't need to know the information, they already knew it.
Seriously though, what is better?
I tried using README files in the repo but there’s far too much friction to get most folks to bother. Google Docs tend to disappear content due to a lack of structure.
Lots of people like to generate a flurry of tiny commits but it's not necessarily the most productive way to work, even without much overhead per change. You can always bundle tiny changes together until it's worth it for you and other people like the reviewer to do the parts that don't scale downwards.
I have confluence links in my Readme, which seems to be a pretty good balance, since it's physically impossible for people to use a search bar in a wiki.
For what it's worth it's a lot better than it was in 2016 but I'm still not a fan.