sia.hackernoon.com

I have been using Confluence for a long time now. I should say the experience so far has been revolting. Read on to know why and learn what Confluence alternatives there are.

Stipulations

This document is highly opinionated. You have been warned. Warning aside, keep an open mind. Just enjoy the review.
This document was not written on impulse. I have been collecting pain points of Confluence for quite some time; every time I got bitten. And I have not mentioned all of it; left some nit-picking ones.
The pain points are primarily based on the expectations of a developer. Confluence may appear to be a boon for a non-developer who is content with blocks and blocks of text with a few other things - tables, pictures, and not keen on presentation. Or they are content with the presentation/rendering too.
I have not listed the pros of Confluence because they are not winning factors. They are just must-haves.
The Confluence I am referring to here is the self-hosted version, and not the cloud version.
Last but not least, this post is not a crusade against Confluence or Atlassian. It is a outrage against a product that in my opinion is simply below mediocre in modern day standards for document writing and knowledge management.

Confluence is unpleasant to work with

Confluence has an extremely unpleasant reading and writing experience

Inconsistent line and paragraph spacing
Non-standard width for document pages. That's horrible. If you don't know what I am talking about, check my extremely naive attempt with CSS for to make Confluence look[^1] like standard page-width document.
It is a shame Atlassian does not support Markdown. It is 2022! Support for markdown is a must-have for any document writing these days.
No control over fonts and styles (except the inadequate presets)
... and many more

There are Uncompromising Downsides to Confluence

No straight-forward way to know with the whom the document is shared with
Lose formatting and sometimes content if the computer goes to sleep (or disconnects from VPN) when left in the edit mode
Unicode / emoji support and copy-pasting rich text from other sources is quirky. Worst is that it would take forever to understand that was the problem.
Usability of commenting is primitive
- There is no view or way (say an on-demand sidebar) to see all the comments.
- Commenting (saving) is erratic when you paste text from elsewhere, especially like a browser. Almost always, comments with unicode characters reports error saving, with a irrelevant error message.
Have you tried reordering the child pages of a given (parent) page? If you have not, you are lucky. There isn't a view that lists the child pages where you can drag-drop or slide up-down and set the child order of a parent page in one go. You do that on a per child page basis to say what the order of that child page is.
Tables are atrocious.

There are Annoying Downsides to Confluence

No mobile app (at least not for self-hosted version). Extremely poor mobile experience in the browser.
In the edit mode ...
- When the content is longer than the current view height, you will see two scrollbars. One is for your content. The other is for the parent container of your content, which when scrolled down will reveal a nav bar sorts with the option to save, publish or discard
No real support for collaborative editing and other collaborative features.
Does not have concept of publishing for sharing. Enjoy the doc update email spam!
AFAIK there is concept of team and spaces and moderators. Just dump everything and make it insanely hard to find in the labyrinth of nested hierarchies. The other option - bookmark of all confluence 🤣. While the organization is usually blamed on the team / personnel configuring Confluence, I see it as an inevitable outcome of a poorly designed product.
Macros are a love-hate deal.

Some Nice Alternatives to Confluence

... in no particular order

The following honorable mentions may lack sophistication such as access control and commenting (in the conventional sense) but bear in mind that vast majority of documentation of open source projects runs on such ones, in some form or fashion.

mkdocs
ReadTheDocs
GitBook (free and paid versions)
... and many more

I spent a decent amount of time and effort experimenting with each of the alternatives above - creating accounts, triaging the features, particularly the ones that Confluence falls short of. I found them definitely way better than Confluence. Each one makes its own trade-off. In other words, no product is perfect but the limitations / shortcomings are beyond the problems that Confluence made me write this post.

My Conclusion

Confluence is the de facto documentation and knowledge management tool of the uninformed.

So is JIRA.

P.S: StackOverflow for Teams is a good option while addressing the Q&A part of the knowledge base.