Rant about Confluence
Over the years I have been using content creation software which had a clear separation of a source and a rendered output. This has been LaTeX for scientific documents, Markdown and reStructuredText for computer documentation. I also use Markdown for my notes with Ghostwriter or Obsidian. I have also used GraphViz to create diagrams and graphs. To create 3D models I have used OpenSCAD, which is a programming language for 3D models. When I needed a Wiki, I have used DokuWiki All these software packages let me use the text editor of my choice, version the source code in Git and share it via GitHub. So for me, having a Git repository of Markdown files is the perfect way to create documentation.
In the average company there are not only technical people like me, but there are also many people who prefer graphical WYSIWYG user interfaces. And I can completely understand that, there are just different workflows and needs. On the other extreme might be a Windows network drive with a bunch of Word documents on it. This would be my personal nightmare, but so would my Markdown setup be to them.
Confluence, a wiki software by Atlassian, is advertised to bridge this gap. It offers the organization of documents in a hierarchy of pages, possibly separated into different spaces. It has access control. And it has a WYSIWYG which caters to the Word-workflow and a wiki syntax editor which caters to people like me who like source code. So in principle it would be the best compromise between the network drive of Word files and the Git repository of Markdown files. And for the most part, it really is that. But there are a couple of things which really make me annoyed with it.
Most importantly: They have killed the wiki syntax editor in 2011. Apparently they have stored the pages in the wiki format internally up to some point. And when they introduced new features, they needed to evolve their wiki syntax. This likely was too cumbersome to represent more and more features, special plugins and the like. The internal storage format now is XML (just like Word and LibreOffice use), and it does makes sense for storing documents with Markup. But it is a pain to edit in source. And they couldn't provide a bidirectional mapping to the wiki syntax because it would require that everything in XML could be represented in the wiki syntax. So they just killed the wiki syntax editing feature. Now there is only the WYSIWYG editor.
The wiki syntax isn't completely gone. One can still type it in the WYSIWYG editor and it gets directly converted into the graphical format. That is okay if one just wants to type content and not format it with the mouse. But it just doesn't let you edit something without using the mouse. One can also bulk import wiki syntax (or Markdown). It just gets converted to XML right away and that's it.
I hate working with WYSIWYG editors. They have invisible formatting markers and you never know on which side of the invisible marker you are on. Say I have something in bold. And then I want to add another word after that. If I click on the end of the bold text, I might continue in bold. Or I might not. It usually happens that I continue typing in bold, then have to select the newly typed text and have to disable bold for that selection again. In Markdown the source would be just
this is **bold** and I could just add something to make it
this is **bold** and this not. I can see the formatting markers and precicely edit it. I don't know to do that with the Confluence editor.
This can also be seen when one uses the
}} syntax to format something with a fixed-width font. When one types the
}}, it applies the font style to the expression and add a space afterwards. They know that if they didn't supply the space, the cursor would pick up the invisible formatting marker and everything behind that would become fixed width as well. But what if I want a period afterward? I have to delete the space that I never typed.
If one is in an enumerated list or an itemize, one cannot escape the list structure by deleting the markers. One cannot escape by hitting enter two times. It just creates more bullet points. I need to click on the list button in the toolbar in order to get back to writing text.
Another annoying thing is that it tries to derive the formatting for pasted text. It surely makes sense if I copy something formatted from Confluence and paste it somewhere else. I want the markup to stay intact. But when I copy an identifier from my IDE to have it in the text, I don't want that to get put into a preformatted paragraph. I just want to have the letters, nothing more. I don't know of a way to paste it without formatting. Even worse, it tries to mimic the coloring that I have in my IDE. That's now how that works. I would create a code block and then it would do a syntax highlighting consistent with the Confluence theme. Up to Confluence 7.9 there even was a bug where pasting code into a code block would discard all leading whitespace. Effectly making it completely useless.
A really painful experience was to find out that if you upload and insert an image which happens to share the file name with any which is already on the site, it will get overwritten. This happened when I downloaded a bunch of images called
screenshot.png from one service and put them into a Confluence page one by one. While editing, the other images were still just fine. But as soon as I saved the page, all old images were gone.
What also annoys me while writing is that I don't have an outline of the document available. With Markdown Ghostwriter I can just open up a panel and navigate a longer document. But in Confluence you are just stuck to scolling up and down if you are a bit lost in your document. You also cannot create split panes in order to do a large global restructuring.
One workaround that I found somewhat suitable is drafting my documents in Markdown. And when I am done, I just import Markdown into Confluence and hope that I don't have to edit them a lot afterwards. That takes away some of the pain, but doesn't work for documents which are shared first and edited continuously. And also Confluence thinks that a fenced code block should just become a preformatted section, not a code block. For this I need to use Pandoc to convert Markdown to Confluence wiki syntax and import that. This often breaks tables where I have put in code literals. And I need to upload the images one by one and put them into the text. So it is annoying.
So in the end I will of course use the platform to share my content. Consistency within a team is important. And the barrier of sharing is super low when there is an agreed upon platform and existing structure. I can of course set up a CI pipeline that renders my Markdown with MkDocs and publishes that to GitLab Pages. But that is just so much more work than just having a wiki that everyone can use.
Rather I wish for Confluence to not make it so hard for developers to nicely use it. Programmers these days all use Markdown for so much stuff. And there is a ticket for Confluence from 2019 where somebody asks for Markdown support. And the status as of writing is “gathering interest”. If you read their blog post with the rationale for removing the wiki syntax, they state that they want to include everyone. I do get that having only the wiki syntax is not okay for people who prefer WYSIWYG editors. And the WYSIWYG editor that they shipped with Confluence 3 was so crappy that it was unusable. Improving that editor turned out to take out so much of their developer time that they couldn't be bothered to maintain the wiki syntax.
Now we have 2021, it is ten years later. They have promised that they would listen to their users, improve the editor and so on. But in Confluence 7, you still cannot edit in some sort of syntax, only the GUI editor. It might be good for a bunch of users, but I have heard from a lot of developers that they are unhappy and unproductive with Confluence. I myself feel the same thing when I write documentation. When the tools support me (Markdown), I am really motivated to write documentation. But when I have to work against my word processor in order to do so, I am quickly annoyed and rather do something else. Developers then turn away from the company wiki and start to document in Markdown files again. Confluence has essentially started as a tool for software developers. Then they wanted to include other user groups with different workflows at the cost of the developer workflow. And by trying to have a one-size-fits-all solution, they have alienated some of their original target audience.