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 editing) feels very off the shelf/MVP, uninspiring UI, the list goes on. It feels like most companies that use it already use the Atlassian stack of JIRA/Bitbucket, then feel the need to tack Confluence onto the end because it's there.
> I can not fathom why anyone would use this for storing documentation for code etc, as opposed to storing things direct in a repo.
Because storing documentation in repos doesn't work great when you want to organize your documentation, discover or search it.
Having thousands of documentation files in a repo, next to the code is unmanageable, much more than thousands of documentation files in Confluence. In Confluence, you can put rights, tags, titles, organize in folders, assign owners, put comments, ....
Is Confluence good at it ? Not much, but it doesn't mean we should remove Confluence.
Confluence is a fantastic way to ensure that nobody ever finds your documentation. The WYSIWYG editor is so painfully slow, buggy, and laggy, it actually reduces the chance of anybody bothering to update documentation. When organizations change names, URLs change completely and you can sometimes never find a linked page again after it moves. Navigation in confluence is painfully slow, even though it's a bunch of static text. Embedding code snippets or images is an exercise in frustration.
Confluence sucks! But it does have one of the best editing experiences I've seen (it also sucks, but less than the rest). You can privately draft pages before publishing them, get diffs of versions, it auto-saves and you even get real time collaboration with others. That's worth a lot, imo.
Interesting. Personally I feel that markdown is a far better editing experience, but that's mostly just a bias towards simple tools. If the confluence editor didn't huff, puff, lag, and choke on even simple documents, I might be able to bear it. But when it takes sometimes multiple seconds for a keystroke to register in the editor, I get so infuriated I just don't bother.
Agree about no one finding your documents. I have trouble finding my own documents in it, don't expect others to be able to find them. Unless you are absolutely obsessive about organisation and linking documents things remain a disjointed mess, would have been cleaner to store markdown in the file system in a directory tree than in confluence.
I mean, I know. I've wrote an article called "We deserve better than Notion and Confluence" and I spend my days building an alternative to Confluence for orgz.
But I still think that Confluence is better than nothing
Also an Atlassian here. For anyone wondering, we tend to use Confluence for planning, decisions, team process, tech specs, etc but use an internal view of DAC[0] for code docs. Think Hugo[1] crossed with redoc[2] with a dash of GraphQL support.
Unfortunately the docs-in-repo + PRs-for-updates approach has way more friction for drive-by-corrections/commentary/Q&A from people not on the team, so it's not a holy grail either.
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 who find the code first can easily find the docs.
> 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.
In my old (and soon current again) shop we used confluence extensively, to get the best from both worlds we usually kept the documentation next to the code in markdown or asciidoc files and synchronized them to confluence in a CI/CD pipeline (confluence was read only for these sections) maybe I can open source these helpers when I'm back... a two way merge was also in the making :). we could sync whole file trees with automatic link crosslink generation, asset management and versioning support in confluence
I face the same problem as our company is heavily using the atlassian products (Jira/Confluence…)
I once found a plug-in that did almost the same, allowed Confluence to read and render markdown files directly from (private) GitHub repos thus allowing me to get the best of both worlds!
- docs stays in the repo (thus is much more likely to actually get updated)
- docs get exposed in Confluence (thus is accessible for the business folks that does not do git)
- docs are easy to update (as you can use any editor: vi, emacs, IDE’s etc)
So conceptually the same as you’re solution ;-)
Unfortunately we did not implement the plug-in as we have too many eggs in the Jira basket (+1.000 users) which have the unfortunate side effect that the licensing price is derived from the +1000 users even though only the much lower number of devs would use it.
That is one repeated problem we face in the Atlassian stack (well a source of their income…)- even a seemingly cheap plugin (extension or whatever they’re called) ends up in the person suggesting how to ‘work smart/not hard’ having to find the funding typically a two digit thousands of € or year (thus I never bother with that anymore :(
In my opinion this is the way to go, documentation close to the code but still indexed in a real knowledge management tool. That's one thing that we are building at Dokkument, but I would be really interested to know more about what you have done, especially how those files are then indexed on Confluence
I always found the ability to draft confluence docs then create jira tickets from within confluence to be the 'obvious' use case, but I don't often see people do it. Or... I've seen some orgs do it a lot, and some not at all (even when they have both jira and confluence together).
Size of org/team is probably a factor, but the linking between the two products is one of the few things I see it has that most other tools don't. It's probably because most other tools are single-use, and they focus on one or the other, but not both sides.
I think Confluence “shines” as a sort of “Wikipedia for your company” with the added benefit that it’s simple enough that anyone can create a nice looking page and there are plugins to cater to different disciplines.
And yes, it’s super bland and uninspiring. Just like Excel or Word. I consider it a feature.
> It feels like most companies that use it already use the Atlassian stack of JIRA/Bitbucket, then feel the need to tack Confluence onto the end because it's there.
Literally the only reason it exists. JIRA is the hook that gets companies on to the rest of the horrible Atlassian stack.
As if jira itself is not horrible. But to be fair to jira I recently tried the cloud version which is untouched by any scrum masters or management and its way better than what I have to endure in my day job with hundreds of customizations it has received over the years to shoehorn every kind of metric
