I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned.
The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API docs). The last two in particular have become a big part of the design process, so it's been bought into heavily. Whether those stand the test of time remains to be seen - they're relatively new.
To me Confluence's problem is the not-very-relevant search, which either gives me generic blank documents that someone created as a placeholder (?!? -- I've started suffixing these with (blank)) or fails to find synonyms or related words when I can't quite come up with the exact search term (wonder if these "related words or synonyms" could be manually added...)
I'm sure it is a difficult problem but I haven't really found any good solutions other than "make really long titles that use many words to describe the content" or "Add lots of tags" and even them I'm not sure it helps or not. Does the search take into account click-through rate? Link count?
> gives me generic blank documents that someone created as a placeholder ... fails to find synonyms or related words ... Add lots of tags
These kinds of problems can be solved using neural networks as the foundation for search (variously termed "neural information retrieval" and "semantic search"). I worked on this at Google Research from 2016-2020, before launching ZIR AI in 2020 to make neural search available as a PaaS, just like Elasticsearch and Algolia have done for keyword matching.
Here are a couple of introductory pieces if you're interested in learning more:
I concur about confluence being where things die. There's a dev on our team that is very big on confluence whereas I'm not. Ironically, I am big on documenting our public methods from the perspective of a user of our library whereas he puts javadocs on private methods. He has more experience than I do, so I don't fight him on it, but man do I find it futile.
> I always find Confluence to be the place where docs go to die
Yeah... I'm not a big fan either. Currently in my team we just use google docs for more dynamic stuff, and have a wiki page with links to all docs. Otherwise we know that people won't bother editing
I agree that this is actually a much bigger deal than it would initially seem.
Any kind of friction is a huge problem when it comes to a task that people are already sort of reluctant to do; just the thought of "ah, fuck, I gotta get two reviews just to add a couple lines of setup instructions?" makes people way less likely to update repo docs as frequently as they need to.
You can always just make the semantics of the doc folder or repo push permissions match what you're looking for, ie. 'no real reviews necessary to push to master' if that's the semantics you're looking for.
The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API docs). The last two in particular have become a big part of the design process, so it's been bought into heavily. Whether those stand the test of time remains to be seen - they're relatively new.