Using tags in Atlassian Jira and Confluence, but things got out of hand? Then I may have some interesting tips for you.
This article is part of my series on the subject.Competition and Discipline: The Pillars of Excellence, where I want to share some of the best practices I've developed over time. So here you can learn to becompetentwhen defining tags in Jira and Confluence.
I will present some basic rules that aim to make homogeneous labels. The value of this is that it makes it easier to work with and find the content you've generated in Jira and Confluence.
The rules that I will present are the following:
- Just English
- only lower case
- Separate each word with a hyphen ('-')
- avoid shortcuts
- Use logic instead of threading
- Use existing tags
The proposed rules have one thing in common:Your goal is to define the simplest approach!Nobody follows complicated rules because they are difficult to remember and implement. Instead, simple rules are followed because they are simple!
Or in other words “KISS”:Just stay stupid![1]
Confluence automatically converts all labels and displays them in lower case. I like this behavior. Unfortunately, Jira doesn't do that. In Jira, you can set labels to be case sensitive. However, under the hood, Jira also converts all tags to lowercase, so case doesn't matter when running JQL queries.
The image above shows that both outputs are labeled "ola.” For TASK-11 with a capital “H” and for TASK-12 with a small “H”. However, Jira encounters both problems when searching "Hello". So the labels mean the same thing but look different. For this reason, I recommend entering all tags in lowercase, as Jira does not convert tags automatically.
For Jira, it takes a little more discipline, but it pays off in the long run. Remember that if you only use lowercase letters, you don't have to think about when to use uppercase and lowercase.
At least in Confluence, you cannot use most special characters when defining a label. It's simply not possible. For example, adding an exclamation point to a tag in Confluence generates an error message.
Unlike Jira, you can define labels with special characters like an exclamation point.
however, sinceSpecial characters mean nothing in terms of contentI recommend avoiding them if possible.
Language-specific characters are an exception to this. In Germany we use so-called German umlauts, such as ä, ö and ü. I consider these characters as special characters as they are not available for people who don't have a German layout keyboard.
If people abroad want to use umlauts, they need to open a character map to enter them. That's a lot of overhead, and as such, people tend to balk at doing it. Meaning, you could end up in a situation where people avoid tagging or create their own tags. The confusion is perfect.
Let me show you the following example[2]:
austria national football team(Austrian national football team)
Whew, what a tough nut to crack! Ö and ß are not common in most countries except Germany and Austria. Even in Switzerland, ß is not an option as "ss" is used there. Therefore, it is better to avoid these signs.
First, this rule asks you to write all the words that make up your tag. This is important because the only way others will understand your label is if you spell all the words. However, we come back to this point with the "do not use abbreviations' Ruler.
Second, the rule wants you to separate all words with a hyphen. The hyphenation is necessary becauseUse only lowercase letters' Ruler. If you don't hyphenate words, your subheadings will be less readable. For example:
glossary article contra glossary article
There are two reasons I suggest using the dash symbol. First, no matter what keyboard layout you use,You only need to press a single key to insert a hyphen. So it's easy, it's easy and it's fast.
domain_driven_designcontradomain driven design
Client: oil industrycontraclient oil industry
Second, it might be logically correct if you create complicated syntax, as shown in the example above. But most of the time, few people, or those who created them, understand these syntactic peculiarities. That's why I tell you to take the simplest approach: KISS.[1]
Having previously worked as a programmer, I also like words written in camel case (or camel case).[3] However, using hyphens is better than using uppercase and lowercase for the following three reasons.
First of all, many lay people are not familiar with the camel case format. Today Jira and Confluence are used by many different people in a company with different backgrounds; Technical and non-technical personnel. Therefore, the approach should be as user-oriented as possible.
The second reason to mention is that when you use camel-case you need to specify whether you want to start a tag with an uppercase or lowercase letter. For example:
glossary article contra glossary article
glossary article contra glossary article
You see, you need an extra rule to clarify how a tag starts, which means extra work. I want to avoid this by writing everything in lowercase and separating every word with a hyphen.
Third, case sensitivity does not work in Confluence because all subtitles are automatically converted to lowercase. When using Jira and Confluence in combination, I recommend following a common pattern for defining tags across both tools.
However, if you say camel-case is the way to go and just use Jira then go for it. The important thing is that you agree to a single standard. And as I said, for simplicity's sake, I recommend hyphenation again.
Using a single language like English leads to more homogeneous labels. In addition, English automatically solves two problems described above:
- By default, there are no umlauts or other strange English characters.
- Words are always split (making them easier to read)
For example:
austria national football team contra austria national football team
glossary article contra glossary article
I tend to work in environments where people come from different parts of the world and they all speak English. Since English is the world's language, it should always be your first choice whenever possible. I think it's a convenient and easy language to learn. If English is not an option, try to find another oneeinzelThe language that best suits everyone.
An abbreviation can stand for many things. To minimize confusion, spell out whole words. This can result in long subtitles, but the auto-suggest feature can save you time here. Therefore, there is no reason to use abbreviations.
From software development and programming, for example, we know a method called “clean code”. It states that to keep (the code of) software understandable and maintainable, you must write understandable code. And one thing not to do when writing clean code: don't use abbreviations for naming artifacts!
The same applies to configuring the tags. An abbreviation can stand for many things. Above all, remember that different people associate different things with the same abbreviations.
Let's say you want to set the labelglossary entryrather thanglossary article. Let's say you work at General Electic and you have the fancy idea of using abbreviations when writing labels. Look what happens:
age contra glossary entry
age contra general energy
With General Electric, you're nothingageautomatically translated to General Electric for almost all employees. You see, what you understand when you see an abbreviation depends on your background.
It gets tricky to concatenate multiple tags into one long tag. Above a certain length, a tag becomes more difficult to read. Another problem is that you end up producing more and more labels because you need an additional label for every box you need to cover. See the following example:
austria national football team
german football team
swiss football team
Poland national football team
…
To keep the total number of tags small and the length of each tag as short as possible, use the specific query language AND operator.[4] For example the tagAustriathe following example can also be used for other purposes.
austria national football team contra Austria national football team
oFootball and national team and Austria
what is moreBasketball AND national team AND Austria
However, there is always a trade-off in the logical division of terms. I always try to find individual terms that have a clear meaning.
glossary articlecontra glossary and article
Obviously, a glossary article is an article in the context of a glossary. However, I'm thinking of splitting it.glossaryYArticleit is oversized. I always decide when to split based on my gut. This is, of course, something that requires experience.
As Confluence version 5.8 was released in June 2015, it is possible to combine tags using macros like thisPage properties reportocontent by tag. Let's see how to create tags with, for example, G.OPage properties reportmacro.
On the left you can see that you can specify an AND operator by adding multiple tag boxes to the filter. In the example above, the result is that Confluence only shows pages that have both tags attached:glossary articleYAgriculture.
When inserting two labels in the same field, it represents the logical OR operation. This means that Confluence will look for all pages that have aglossary articleOAgricultureadjunct.
Using a minus sign (or hyphen) as a prefix to a label represents the NOT operator. That is, in this case, Confluence looks for all pages that have aglossary articleattached but not marked withAgriculture: glossary article AND NOT(Agriculture).
At this point, Confluence is behaving a bit strangely. I expected the minus sign tag to be added in a separate tag field as it would translate as "AND NO". However, the mode of implementation may make sense from a technical point of view.
The last rule is obvious. Try to keep the number of tags to a minimum to avoid irritation. Jira and Confluence will help you with suggestions. use the
Also, within Confluence, I recommend having a single page per space where the macrotag listit is used. You can configure it to display all tags used in a space. In this way, you can control and manage the tags with an overview. You must also set up a page that defines the rules for the tags. I always put everything on one page and make it explicit. Just look at the image below.
However, you should also monitor and clear tags from time to time. That means you need someone to do it too. This person should educate and remind all team members to define labels properly. As I always say, it is never just competence (knowing how to do it), but also discipline (really doing it). And competition depends on discipline.
[1] From Wikipedia: "The KISS principle states that most systems work best when they are kept simple and uncomplicated." adopt a method or, in this case, a rule. read thisWikipedia article on the KISS principle.
[2] Yes, I sayAmerican footballrather thanAmerican footballsince I'm not from the US. And yes, I know there is an explanation that the ball in football is a foot long. Having grown up in a country that uses the metric system, I don't understand why this is called a game.American footballwhen people hold an egg in their hands, they rarely kick it. Therefore, I recommend changing the name of this sport tothey handball -orugby americanoif you like. In other words:royal with cheese.
[3] Read more about case notationthis Wikipedia article. Worth noting: the German term for a camel's trunk is "Binnenmajuskel". German is a great language. Life is too short to learn German anyway (unless you grew up speaking it natively).
[4] The query languages are Jira Query Language (JQL) and Confluence Query Language (CQL). Atlassian has excellent documentation to help you explore these languages in more detail. Take a look at this page:https://confluence.atlassian.com/