How to avoid confluence as much as possible

November 23, 2020 3-minute read

Introduction

Some tasks should be done with as little resistance as possible. Writing documentation is one of those things.

My employer has bought in to the Atlassian stack big time. We use Jira to manage our projects, host our code on BitBucket, and document on Confluence.

Sure, the stack can be heavy and full of unnecessary bells and whistles, but on a principle level, I like many things here.

However, I am not too comfortable using the confluence WYSIWYG interface. It's a bit bloated and at times very slow. I do like writing code in my editor though, which is emacs, and especially here I like writing with the org-mode markup language which has top of class emacs integration.

Finally, I don't really trust wikis. Many years ago, a previous employer lost years of documentation, because someone forgot to back up the wiki server, so if I write something, I want to have offline copies, and ideally I want to be able to check everything in to git. Even though Confluence has versioning, git's versioning is much better and easier to manage.

How I write documentation

Currently, I write a lot of architecture documentation. I design network automation models that we will develop using Cisco NSO, as well as describing network designs and other supporting documentation for our automation projects.

These documents are best stored in our central confluence, so that other people can find them and reference them.

My process now starts with an org-mode file that I write in emacs. Using org-mode I can write tables and code examples super easy.

As not everything can be described in words, I try to create all my diagrams using plantuml. This is also built in to org-mode and emacs, so I can pre-view them on the fly.

While plantuml may sound like overkill, it's actually not. The language is quite powerful, and the diagrams themselves can often be done in less than 20 lines of code. I can usually express simple conceptual diagrams, as well as processes and flows using the simple markup language.

One extra bonus is that I can keep my diagrams embedded in the text itself, and since Confluence natively supports plantuml, I don't have to render any files offline.

Of course, sometimes plantuml isn't the right tool for the job, and in those cases, I upload an image file.

From writing everything in org-mode, I gain the ability to export my documentation in to almost any desired format using pandoc. And it does support a lot of formats, even including Microsoft Office formats.

The workflow

In the beginning, I could handle the manual process of exporting to Confluence. I started with the built-in ox-confluence (an emacs package to export from org-mode to confluence).

My amount of documentation was small, so copy-pasting the resulting confluence markup was possible to handle.

However, I ended up with a lot of individual confluence pages that all needed to be kept in sync.

The solution ended up like this:

A git post-commit hook iterates over all files that have been updated in a commit
For each updated file, they are converted to Jira format using pandoc, and a

I'm using https://github.com/atlassian-api/atlassian-python-api to handle the REST connection to Confluence.

I also have a few functions that fix various shortcommings of pandoc, such as:

Converting plantuml code in to plantuml macro blocks so the diagrams are
Uploading images and fixing the converted confluence content to use the