So, it’s no secret that I deal with more than a few systems whose primary purpose boils down to “Display text.” The obvious example that should come to mind is this very thing you’re reading right now. WordPress.com powers this site, and learning to use its text editor has been…interesting. Before that, I ran MediaWiki and PhpBB (versions 2 and 3…was in that game for a LOOONG time). All that being said, one of my favorite editors to work in has to be Jira’s sister product, Confluence.

While not as flexible as something like a word processor, it still gives me enough flexibility to create some really outstanding Documents and Blog posts. Honestly, when I initially set up The Jira Guy, I debated running it on Confluence. However, I decided against that – mainly because I run websites for a living. At that time, I didn’t expect this side project to become anything, and I didn’t want to spend too much effort on keeping it running. Funny, right?

But I digress. Having worked in Confluence for many years, I have picked up a few tricks to help my documents stand out. So I figured it’s about time I spread my wings a bit and show you that this Jira Guy can also work Confluence!

Page Layouts

 Page Layouts lets you set up how different elements are spaced amongst each other and is one of the most underutilized formatting options. To display this sub-toolbar, you need to click the “Page Layout” button on your Confluence Toolbar – as shown below. This will open up some tools for you to use.  

The first section is for adding and removing a section. Clicking “Add section” will add another row below whatever section you are currently working in. Comparatively, the “Remove section” button will remove your currently selected section. Be careful, though; it will also remove any contents in that section. If you accidentally hit this, you can undo it with a ctrl-z or command-z (depending on the operating system). 

Next, we have the Move buttons that move the section you are currently in relative to the others. After that, we have my favorite buttons. These control how many columns your currently selected section has and their size relationship with one another. This is where I get into my tips and tricks.

One of my favorite things to do is to have a little information panel at the head of the document. This section can have information about who wrote the document, a table of contents, or details about who this page is for and why they need it. Combine this with some formatting and editing, and you get this nice “indent section” look for your document. 

But wait, there’s more! Using different layouts as you go down the document can let you include sections for a picture and vary where that picture is. This arrangement can add a more dynamic look to your document, one I enjoy. 

Another use for sections is to align different elements vertically. Take this document, for example. Here, I wanted a two-column approach for the whole document. However, I wanted to ensure that the second section in each column, “Skills” and “Blog” were aligned. 

So to do this, I put in a second section with the content I want to be aligned starting on that new section. By doing this, you can align items among columns where the content length above might be dynamic. However, this does run the risk of having white-space gaps on the sections above – especially if the content in the two columns is vastly different in length. However, this is where careful editing and formatting can help – in this case, I’ve carefully curated the paragraph and macros in the second column to match the first, hence the warning at the top. In speaking of warning, that brings me to my second tip…

Info, Note, Tip, and Warning.

My next tip is for drawing attention to detail. For example, let’s say you are writing a document. There is a critical step that is also very tricky or otherwise easily missed. How do you draw attention to this tidbit that could otherwise save the reader hours of headaches?

That’s where this series of Macros come in. Using the Info, Note, Tip, or Warning macro generates a small text box of that color, allowing you to draw attention to various details that you want to ensure readers don’t miss.

I should note that these macros have *slightly different* names in Confluence Cloud but otherwise serve the same function.

Color	Confluence Server/DC	Confluence Cloud
Blue	Info Macro	Info Panel
Green	Tip Macro	Success Panel
Yellow	Note Macro	Warning Panel(!?)
Red	Warning Macro(!?)	Error Panel

These macros, when appropriately used, can take a document from good to fantastic because it shows the readers where the dangers are and where they need to pay special attention to something. Even if it is only “This person is a work in progress, and should not be taken seriously until otherwise said.”

Jira to Confluence Integrations

Did you really think we were going to go two weeks without taking something Jira? Nope! This functionality is one I’ve seen used a lot of, but I wanted to draw special attention to it – as there are some best practices here that you should be aware of. 

First, though, Background information needs to be given. The Jira Macro in Confluence allows you to display either a single issue or a group of issues returned from a JQL String. Furthermore, each time the page is loaded, it gives you the latest status of the issues searched. This allows you to have pages that reflect the current state of affairs in Jira, thus bringing your pages to life.

Here’s the warning, though – you can go overboard. Let me share a story. At one point, I got a ticket in saying Confluence was slow. I had been chasing intermittent lag spikes in Confluence for a few weeks and was no closer to solving it, so this felt accurate. Still, I asked for the specific page they were experiencing slowness, hoping for a clue to the overall puzzle. Boy, did I get that clue!

The PM who filed the ticket gave me a page that caused my machine to lag hard trying to load it. Once it did, I saw why. This PM was preparing notes for the new release, including every issue that was included in it. Each one queried as a single issue. Some issues were referenced multiple times.

All told, I counted some 500 single issue queries going from Confluence to Jira. No wonder it took so long; my browser had a lot of communications to do with Jira to load and display all the information. As you can guess, this document was by itself the source of those lag spikes. Every time someone in the organization loaded up the page, Jira and Confluence would show a spike. 

Okay, so the document was needed, so how do we get around this? Well, we need to consider overhead. For example, is it more efficient to have a single query that returns 20 issues or 20 queries that return one issue each? The answer is the single query that returns 20 issues. The total number of issues returned is the same in both cases, but each query has an overhead associated with it. The result is that the 20 single-issue queries have more overhead time than the single query. 

Of course, this example took that to the extreme case. But it’s still something you should be aware of as you guide your users through best practices. 

So, what do you think?

I’m trying to vary my writing and include content that is not strictly “Jira” related. Do you like this? Are there any other topics you’d like me to cover? Let me know in the comments! I will say this, though – I intend to get back to Jira next week.

Don’t forget you can find me on social media through my Linktree link. So stop by and share your thoughts and comments; I love hearing from you! You can also find links to support me directly; any help you give is immensely appreciated!

You can also sign up below to receive blog posts via email. I can’t count the number of times I’ll see the new post in my inbox before I get the notifications it’s been posted on Social Media. It’s absolutely the best way to ensure you don’t miss new posts!

Also, don’t forget I’ll be live on Youtube this afternoon at 5:00 PM Eastern, 2:00 PM Pacific, where I’ll be going over these tips live on Confluence, as well as a couple of tips I didn’t include here! Hope I see you there!

But until next time, my name is Rodney, asking, “Have you updated your Jira issues today?”