The Admin's tale - Fun with labels, not with flags

[#1]

Once upon a time, the admin was asked, what these labels on all the Confluence content are used for. He already noticed that people do always forget to add labels and he asked himself, why they don't use them. He thought that maybe it's because they don't know what magical and useful things they could do with labels, if they would use them. They even would have some fun with labels, as much as they already have with this little YouTube series about flags.

So, this time the admin decided to not answer a specific question but to write an article about labels. 

What can be labelled in Confluence?

Almost anything - Pages, Blog Posts and Attachments - even spaces if you treat space categories as some kind of a special label. But I won't do that here, nope, no space categories. Maybe another day...

How do I add a label?

Did you see that small little pencil on the bottom of your content? This is not just a nice decoration, it is the way you add a label to your content. Click on the icon and simply add your label(s) - no big magic, waving wand and cast a spell is also not required (but it may help), it simply costs some seconds, so do it :-) - You don't even have to open the page in edit mode!

I can't see the pencil :-(

If you don't see the pencil icon on a page, then you are probably not allowed to edit the page. Ask your space or system administrator for help. And if you are the system administrator, ask the Community ;-)

I can't add a label that consists of two words!

Yes, that's true. You can't do that.

You won't believe, how many "and", "or" "by", "but", "as" - labels the admin found in his Confluence instances. Of course, the pages with the "and" label are not about the proper grammatical use of the small word "and". Often, the page doesn't even contain the word "and". But why do people add that label to their page? That is because they want to add a label with blanks, e.g. "Batman and Robin":

 

 and get three labels after adding that label:

 Even putting the whole thing in quotation marks doesn't help:

results in:

And that is even worse then before :-(

So, short conclusion: one word - one label, second word, second label and so on. If you want to have labels with two words, you have to seperate the words with a "-"-sign or an underscore:

results in:

How do I get rid of all these wrong labels?

If you have tons of these great "and"-Labels and want to remove them completely, you are lost. You don't have to fight against a smoke monster, but it is a similar experience. Deleting a label means: removing that label from every single page this label was added. If the last one is removed, the label has gone as long as the next user wants to add a "Batman and Robin"-label.

My Labels Are LowerCase But I Love These UpperCase Words

Labels are lowercase. Always. You can't add uppercase characters. No matter how much you wave your wand.

OK, now I have some labels, what is the benefit?

Of course, this is the most important question, the admin has to answer in order to get people adding labels. They need to see some meaningful results for the things they are doing. So do I  (btw, say thank you to your admin from time to time, most of us like that :-) ).

Search improvements

First of all: No, no no, you can't bring your page to the top of the search results by adding labels. The ranking of the search result is much more complicated, Atlassian has revealed a bit of the algorithm here:

https://confluence.atlassian.com/confkb/how-do-i-understand-the-ranking-of-confluence-s-search-results-785614686.html

As you can see, labels have no big influence on ranking. But of course, labels are indexed. If you search for a label, e.g. "Batman and Robin" you get the page with the label, even if the words aren't on the page itself.

Searching for pages with a label is quite easy: Add a filter on the Search page. You find the filters on the bottom of the sidebar on the left:

 

The search result by searching with labels can be much better than the full index search. But, it depends extremely on the quality of your labels. If the usage of labels is poor, searching with labels is bad. But it is never too late to improve the quality of your labels, start now!

Another way of searching for labels is: type "labelText:batman-and-robin" as your fulltext-search. Please note that the "T" from labelText has to be written in uppercase letter. Otherwise, it won't work.

What else can you do with labels?

A lot of functionality in Confluence is based on labels. There are macros and templates using them. I will not describe add-ons from the marketplace here, just the out-of-the-box-functionality of Confluence. Here are some examples for label magic: 

Very simple magic: click on the label

If you click on a label, you are redirected to a page, listing all other pages labelled with this label and other labels, that seem to have anything in common with the clicked label:

(Seems that Confluence has some knowledge about Marvel Comics... How these related labels work is explained later).

Macro "Content by Label"

This macro lists all pages with a special label. Result can be sorted by title, creation date or last modified. It looks like that:

With this plugin, you are able to build great dynamic lists of pages with a special label. This list may be better than just searching for the label text.

Macro "Content Report Table"

This macro is displaying also a list of pages with your label, but in another style and other data as well:

Macro "Labels List"

The macro "Labels list" creates a list of all your labels in alphabetical order. You decide, if you want to show labels from all of your Confluence instance or just from one space. The list looks like that;

and each of these link leads to a list of the labelled content.

Macro "Navigation Map"

A "Navigation Map" lists all pages with a label in a tabular form:

The cells links to the referenced pages. I think, this looks a little bit old-fashioned, but it still works.

Macro "Popular Labels"

This macro shows the most popular (= most used) labels in your Confluence instance or in your space. It creates either a list in alphabetical order (looks similar to the "Labels List") or as a heatmap. A heatmap looks like that:

The bigger the font, more often the label is used.

Macro "Recently Used Labels"

This macro lists the last used labels in your Confluence instance or in a space. It lists these labels either as a list:

or as a stream:

 Macro "Related Labels"

This is an interesting macro. Really really useful. It shows pages that has similar labels than the one added to your page. 

With this macro you can build functionality like "These pages might be also of interest for you". Here is an example:

How is this working? Is my Confluence reading Marvel comics? Of course not, but it would be a nice idea ;-)

The relationship is built upon other pages that have both labels (e.g. batman-and-robin and poison-ivy) appended. That's all, hope you are not too disappointed.

But I love the idea of my Confluence reading comic books in the night...

A few years ago, there was a really great macro: Dynamic Content by Label. This macro took all the labels from the current page and proposed other pages for further reading based on related labels. This macro stopped working two years ago and I am still missing that, it was great. Maybe you can vote for the suggestion to upgrade the Content by Label macro to a similar functionality: https://jira.atlassian.com/browse/CONFSERVER-38753 

There are many other add-ons on the marketplace that promise to improve the usage of labels in Confluence. Do you use one of them? Tell us your experience in the comments to this article!   

Use labels in templates and Content Reports

If you create a page template in Confluence, add a label to that template! So you can be sure, that each page, created with this template can be found by its label.

Some popular and useful built-in templates such as the meeting-notes-template add a label automatically to the new meeting-note-page when it is saved.

The overview page for meeting notes then lists all the meeting note pages created with the template. It finds them, guess what, by the label. Nothing else.

The main component of the meeting notes overview page is a "Content Report Table" macro. If you look at this macro in detail you find, that it searches for pages from the current space with the label "meeting-notes". It shows some data from these pages, e.g. Title, Creator, Modified, Comments, ... You can use this macro by yourself to create powerful dynamic lists of your content, but be sure to always add labels to your content!

Special Interest

For those of you who want to provide or use a link to the built-in-Confluence-page showing all the content labeled with e.g. "batman-and-robin", you can use this URL: http://<your.Confluence>/label/batman-and-robin

On this page, you find all the pages with this label and all the related labels.

So, you can build great functionality with labels, label macros and templates with labels. I hope, the admin could give you some new ideas for using labels in Confluence.

But where is the promised fun?

Wasn't it funny enough? I think it was at least as funny as Fun with Flags, but OK... I've got one more thing for you:

Try the add-on "TagCloud for Confluence". It is for free, but for Server instances only. It visualizes your labels as rotating 3D-Globe or as a star. And with this star, maybe you can put a smile on your user's face at the right season of the year (I had to scramble all the labels here, but in real life, each of these blurred lines was a clickable label):

Have fun everyone :-)

[Trejkaz]

This page suggests that labels will magically disappear when the last occurrence is removed, but this is not what I see happening in Confluence Questions. Empty labels stick around ready for people to misuse them again.

Some way to properly delete labels would be very useful. A way to ban certain labels, or to set aliases so that they automatically rename to the right label, would be even more useful.

[Thomas Schlegel]

Hi Trejkaz,

I'm not using the Questions plugin for Confluence. My article refers to plain Confluence only. There you can't rename or delete a label from all pages, as far as I know. There might be some plugins that provide solutions for this problem, but I didn't tried any of them yet. Maybe the usage of labels is different in Questions for Confluence.

Also, you can't restrict the usage of certain labels in plain Confluence.

I've just tested the removal of labels. If the last occurence of a label is removed, the label disappears from the Labels List macro. Tried that with Confluence 5.10.7

But I agree with you, the administration of labels in Conflunence could be improved...

[Trejkaz]

Ah... that Questions plugin must be inventing its own thing instead of using existing labels. It's too bad... it's made by Atlassian too, if only it could behave like the rest. :(

We have a real problem on Questions, where the permissions are such that any user can create bad labels, but only moderators can edit posts to fix the labels, and only admins can fix things like a typo in the label itself. Since only IT are admins, this means that nobody can ever do any real cleanup, while permissions to mess up the tags have been given to literally everybody.

If it were me, I would have restricted normal users from creating new labels and allowed only moderators to do that, to at least contain the damage, but even then, sometimes you mistype something, and when you mistype labels, they're like that forever. :(

[danbroun]

Why can labels not be found through the quick search....? That is very disappointing. I always need to search twice.

[Christoph Pichlmann]

Good read, but it's missing something I'm currently looking for - is there a way to edit the "Content by Label" page?
I want to add a short description about what that label does and where it applies, so anyone who clicks on the label anywhere can simple read up about it.

Compare it with MediaWiki categories, where the category itself has a page of its own.

[Angela L_]

This is a very helpful article, thanks. But with the exception of Dr. Strange, those are all characters from DC comics, not Marvel! :)