Glad to see any alternatives to confluence (or Atlassian in general). I've used Confluence for a good 4 years or so and for the life of me, I can not fathom why anyone would use this for storing documentation for code etc, as opposed to storing things direct in a repo. I can understand it's use somewhat for business folks, but even then, the way of organising things is abysmal, every solution (such as rich text editi…
There are a couple reasons I prefer docs in Confluence to docs in repo: - I can update the docs without going through Git peer-review (admittedly this is a culture issue, not a technical one). - We have "code-tangential" docs already in Confluence and it's nice to have one place to search - Non-devs (like lawyers) find Confluence more familiar I've taken to putting a link to the Confluence docs in the README so folks…
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.