Using Labels in Jira and Confluence — Effectively and Efficiently
You are using labels in Atlassian Jira and Confluence, but things got out of hand? Well, then I may have some exciting tips for you.
This article is part of my series on Competence and Discipline: The Pillars of Excellence, where I want to share some of the good practices I developed over time. So here, you can learn how to be competent when setting labels in Jira and Confluence.
In Short
I will present some basic rules that aim to produce homogeneous labels. The value of that is that it becomes easier to work with and find the contents you have generated inside Jira and Confluence.
The rules I am going to present are as follows:
- English only
- Lower case only
- Separate each word using the dash symbol (‘-’)
- Avoid abbreviations
- Use logic instead of concatenation
- Use existing labels
The suggested rules have one thing in common: they aim to establish the most straightforward approach! No one follows complicated rules since those are hard to remember and implement. Instead: simple rules are followed because they are simple!
Or, in other words, “KISS”: Keep it simple, stupid![1]
Use lower case only
Confluence automatically transforms and displays all labels in lowercase. I like that behavior. Unfortunately, Jira is not doing that. In Jira, one can set labels in uppercase and lowercase notation. However, under the hood, Jira also transforms all labels to lowercase so that the spelling does not matter when you execute JQL queries.
The image above shows that both issues have set the label “hello.” For TASK-11 with a capital “H,” and for TASK-12 with a lowercase “H.” However, Jira finds both issues when searching for “Hello.” Therefore the labels mean the same, but they appear differently. And that is the reason why I recommend entering all labels in lowercase, since Jira does not transform labels automatically.
For Jira, it requires some more discipline, but it pays off in the long run. Keep in mind that you don't have to think about when to use uppercase and when to use lowercase when only using lowercase labels.
No special characters
At least in Confluence, you cannot use most special characters when defining a label. It’s simply not possible. For example, adding an exclamation mark to a label inside Confluence ends up with an error message.
Contrasting in Jira, you can set labels using special characters like an exclamation mark.
However, since special characters do not express anything in terms of content, I recommend avoiding them whenever possible.
An exception from that are language-specific characters. In Germany, we use the so-called German umlauts — like ä, ö, and ü. I regard those characters as special characters as they are not available to people when they do not have a keyboard with a German layout.
When people from non-German countries want to use umlauts, they must open a character table to insert them. That’s a lot of overhead, and thus, people tend to refuse to do that. Meaning it may end in a situation where people avoid setting any label at all or where they create their labels. The confusion is perfect.
Let me show you the following example[2]:
österreichische-fußballnationalmannschaft (Austrian national football team)
Phew, that’s a tough one! Ö and ß are not common in most countries other than Germany and Austria. Even in Switzerland, ß is not an option since they use “ss” instead. So it would be best to avoid these characters.
Separate all words with a dash
First, this rule asks for writing out all words your label consists of. That is essential because your label will only be understandable to others when you write out all words. However, we come to this point again with the ‘do not use abbreviations’ rule.
Second, the rule wants you to separate all words using the dash character. The separation of words is necessary because we want to follow the ‘use lower case only’ rule. If you are not separating words, your labels will be less readable. For example:
glossaryarticle versus glossary-article
There are two reasons why I suggest using the dash symbol. First, irrelevant to whatever keyboard layout you are using, you only have to push a single button to enter a dash. Thus, it’s simple, it’s easy, and it’s quick.
domain-driven_design versus domain-driven-design
customer:oil-industry versus customer-oil-industry
Second, it may be logically correct when you create a complicated syntax, as shown in the example above. But most of the time, those syntactic quirks are only understood by a few people or those who created them. Therefore I say follow the simplest approach — KISS.[1]
Since I used to work as a programmer, I also like words written in camel-case (or CamelCase).[3] However, using dash is superior to camel-case for the following three reasons.
First, many non-technical people are not familiar with the camel-case format. Nowadays, Jira and Confluence are used by many different people in a company with diverse backgrounds; technical and non-technical staff. Thus, the approach should be as user-oriented as possible.
The second reason to mention is that if you use camel-case, you have to define whether you start a label with an uppercase or a lowercase character. For example:
glossary-article versus GlossaryArticle
GlossaryArticle versus glossaryArticle
You see, you need an additional rule to clarify how to start a label, which adds extra effort. I want to avoid that by writing everything in lowercase and separating all words with a dash.
Third, using camel-case does not work in Confluence since it automatically transforms all labels to lowercase. If you use Jira and Confluence in combination, I recommend following a common standard on how to define labels across both tools.
However, if you say camel-case is the way to go and you are only using Jira, do it. The only important thing is that you agree on a single standard. And as I said, due to simplicity, again, I recommend separating using a dash.
If possible: use English
Using a single language like English produces more homogeneous labels. In addition, English automatically solves two problems described before:
- By default, there are no umlauts nor other strange characters in English
- Words are always separated (and thus better readable)
For example:
österreichische-fußballnationalmannschaft versus austrian-national-football-team
Glossarartikel versus glossary-article
I usually work in environments where people come from different parts of the world, and everyone speaks English. Since English is the world language, it should always be your first choice, if possible. I think it is a language that is comfortable and easy to learn. If English is not an option, try to find another single language that serves everyone best.
Spell in whole words: do not use abbreviations
An abbreviation can stand for a lot of things. To minimize irritation, spell in whole words. This may lead to long labels, but the auto-suggest feature can save time here. So there’s no reason for using abbreviations.
For instance, in software development and programming, we know a method called “clean code.” It says that you should write understandable code to keep (the code of a) software understandable and maintainable. And there is one thing that you should not do when writing clean code: do not use abbreviations for naming any artifacts!
The same is true when setting labels. An abbreviation can stand for many things. Most importantly, always remember that different people associate different things with the same abbreviations.
Let us assume you want to set the label glossary-entry instead of glossary-article. And let us say that you work at General Electic and you have the fancy idea to use abbreviations when writing labels. See what happens:
ge versus glossary-entry
ge versus general-electric
At General Electric, the label ge automatically translates to General Electric for almost every employee. You see, it depends on your background what you understand when you see an abbreviation.
Use logic instead of concatenation
By concatenating several labels to one long label, things get complicated. Given a certain length, a label becomes less readable. Another problem is that you produce more and more labels because you need an extra label for any case you need to cover. See the following example:
austrian-national-football-team
german-national-football-team
swiss-national-football-team
polish-national-football-team
…
To keep the overall number of labels low and the length of each label as short as possible, use the AND operator of the respective query language.[4] For instance, the label austria in the following example can also be used for other purposes.
austrian-national-football-team versus national-football-team AND austria
or football AND national-team AND austria
additionally basketball AND national-team AND austria
However, there is always a trade-off when splitting up terms by logic. I always try to find single terms that have a clear meaning.
glossary-article versus glossary AND article
Of course, a glossary article is an article in the context of a glossary. However, I think splitting it into glossary and article is over-engineered. I always decide on gut feeling when to do a split. Of course, this is a thing that takes experience.
Combining labels in Confluence
Since Confluence version 5.8 was released back in June 2015, it is possible to combine labels when using macros like the Page Property Report or Content by Labels. Let’s see how to combine labels using e. g. the Page Properties Report macro.
On the left, you see that you can set an AND operator by adding multiple label fields to the filter. In the example above, the result is that Confluence only shows pages that have both labels attached: glossary-article AND farming.
By typing two labels in the same field, it stands for the logical operation OR. That means Confluence searches for all pages which have glossary-article OR farming attached.
Using a minus (or dash) as a prefix to a label stands for the NOT operator. That means, in this case, Confluence searches for all pages which have glossary-article attached but are not tagged with farming: glossary-article AND NOT(farming).
At this point, Confluence behaves a little strangely. I would have expected the label with the minus to be added in a separate label field since I would translate it to “AND NOT.” However, the way it is implemented may make sense from a technical point of view.
Try to use existing labels
The last rule is a no-brainer. Try to keep the number of labels at a minimum to reduce irritation. Jira and Confluence will help you with suggestions. Use it.
In addition, within Confluence, I recommend having a single page per space where the macro Labels List is used. You can configure it to show every label used inside a space. In that way, you may be able to control and manage labels by having an overview. You should also set up a page that defines the rules for labels. I always put everything on a single page and make it explicit. Just see the image below.
However, you also need to track the labels from time to time and clean up. It means you also need someone who is doing that. This person should teach and remind all team members to set labels appropriately. As I always say, it’s never just about competence (to know how to do it) but also discipline (actually doing it). And competence is interdependent with discipline.
Footnotes
[1] Taken from Wikipedia: “The KISS principle states that most systems work best if they are kept simple rather than made complicated.” I always say that the lower the hurdle to take, the more likely it is that people adopt a method or, in this case, a rule. Read the Wikipedia article about the KISS principle.
[2] Yes, I say football instead of soccer since I am not from the USA. And yes, I know that there is the explanation that the ball in American Football is one foot long. Since I grew up in a country where the metric system prevails, I don't understand why calling a game football when people are holding an egg with their hands that they only kick exceptionally. Thus, I recommend renaming this sport to Egg Handball — or American Rugby if you want to. In other words: Royal with Cheese.
[3] Find more information about the camel-case notation by reading this Wikipedia article. Noteworthy: the German term for camel-case is “Binnenmajuskel.” German is a great language. Anyways, life is too short to learn German (unless you were grown up as a native speaker).
[4] The query languages are Jira Query Language (JQL) and Confluence Query Language (CQL). Atlassian provides excellent documentation where you can explore these languages in more detail. Check out this page: https://confluence.atlassian.com/
