2017
26
January

Confluence Greatness

Yes, I’m an ‘Expert’ by title (a term that is thankfully changing soon) and my profession is an Atlassian consultant with Isos Tech. That doesn’t mean that everything here will apply to every situation.

I can talk about cooking chili, I can even share my recipe and show you to make my (mom’s) chili. I can’t, however, make you like it. Nor can I make you make it. This is a collection of recipes and cooking tips, they may or may not be useful in your company, culture, or Confluence instance.

In order to understand how to unlock the awesomeness of Confluence, you have to understand how the tool works and map the functionality and featureset to the particular strategy or initiative that you are most concerned about. For our purposes here, I’ve chosen to focus on Knowledge management (KM) and am leveraging some info from Wikipedia[1to help level set what KM is.

Knowledge management (KM) is the process of creating, sharing, using and managing the knowledge and information of an organization.[2] It refers to a multi-disciplinary approach to achieving organizational objectives by making the best use of knowledge.[3]

I interpret this to be the culture that an organization has around information which differs from Content management (CM) which is more focused on curation and Information management (IM) which is the akin to stewardship.

Many large companies, public institutions, and non-profit organisations have resources dedicated to internal KM efforts, often as a part of their business strategyinformation technology, or human resource management departments.[4]

Knowledge management efforts typically focus on organizational objectives such as improved performance, competitive advantageinnovation, the sharing of lessons learned, integration, and continuous improvement of the organisation.[5] These efforts overlap with organisational learning and may be distinguished from that by a greater focus on the management of knowledge as a strategic asset and a focus on encouraging the sharing of knowledge.[2][6] KM is an enabler of organisational learning.[7]

Quick example
If we look at knowledge as food (one of my favorite topics), think of IM as sort of the Food and Drug Administration (FDA) as they set high level policies and perform sweeping regulatory actions. CM, then, is more like the Supply Chain, where’s the food, where does it need to be, what kind is it. KM is more like cooking and eating, always better with friends.

Wiktator, gardener, and champion

Although KM focuses on building a culture and best practices around information, I’d be lying if I said that it would be easy to do. With the incredible flexibility and extensibility of Confluence, you still will want to have an owner to ensure that all the work that goes into IM, CM, and KM stays on track. Consider hiring an ACP – Confluence Professional when it makes sense for your organization. If you can’t afford that investment today, look at growing that skillset from your Application, Business, and/or QA Analysts, Scrum Masters, or Technical Writers. Those are all roles that map well to Confluence administration at the Space level.

How to

Great presentation on getting KM going and if you pay attention, you’ll not only see the how, but you’ll get a really solid inside look at the “who.” As in, the type of person you need to hire.

Summit 2015 – knowledge-sharing-culture

What’s in a page?

Shakespeare’s Juliet said “What’s in a name? That which we call a rose by any other name would smell as sweet.” A rose is a rose because we’ve all come to acknowledge and accept that is what it is. Likewise, a page is a page because we agree that is what it is called. One more step. So what you put in a page, should be what you (the collective you, your organization, your team) agree goes in a page. I’m hoping you understand why I led with KM now.

There’s no theoretical limit on Confluence pages. There’s no extra cost to make a bazillion Confluence templates. Basically, you can have a page and/or template for everything and anything. HR onboarding checklist? Do it! One-on-one or coaching notes? Done! Quarterly and Annual reviews? Easy sauce! Monthly audit documentation? I think you get it.

Once you get your team fired up about Confluence, you’ll have pages everywhere for all kinds of things. So, before that happens, agree to some basic guidelines around Information Architecture. This can be formal, but certainly doesn’t have to be. What goes into a page title? What’s your information retention policy? How do you determine what needs a new space (my rule is if it doesn’t have a Jira project, it most likely doesn’t need a Space)? When do you use a new parent page to add a branch of documentation?

If you are going to make a page of a type X more than once, consider a template. Global templates can exist for any reason and you can create localized (space) versions as well. So just do it! A great example is meeting notes. You may want a certain layout for your notes and agenda that applies to the organization as a whole (Global), but each team shouldn’t have to type in their specifics each time (Space). Define the structure globally and allow your teams to focus on the content.

Where these really get powerful is when you combine templates with macros and start automating your IM/CM! In addition to the physical layout of spaces and pages, consider how you want to structure labels as that is where you can make the biggest impact in Confluence.

Labels are going to be very organization specific. A good example are the how-to and troubleshooting labels that come with Confluence. By themselves, they aren’t terribly helpful, but when combined with other labels, they can drive some really great results. When using Confluence as a linked Knowledge Base (KB) for Jira Service Desk (JSD), some how-to articles might have hardware added as another label to further refine search parameters. Taking it another level, you might have an article with how-to, hardware, and printer labels and another with how-to, onboard, and new-hire.

This is a really simple taxonomy or structure for your labels. At the top level you have the template name or type of document, followed by a process or subdivision of the top label and finally a subcategory or subprocess. This three level structure should cover the majority of use cases and bring joy to the land!

Thanks dude, but where were you 5 years ago?

And then reality sets in. You’ve inherited a train wreck or have been forced to watch your Confluence instance devolve into the digital equivalent of Lord of the Flies.

Now, people are complaining, I can’t find anything, I can’t find anything, this search is terrible! GIGO, at least there’s plenty of blame to go around.

Confluence is a terrific platform for collaborative work within an organization. But over time difficult-to-search and unconnected silos may develop as independent teams within the group continue to create their own documents and file hierarchies, trapping valuable data. Teams may duplicate effort if the information they need is stored in subdirectories they are unaccustomed to checking and requires too much effort to find. The result is frustrated users and diminished productivity. [1][8]

That’s not to say there isn’t room for improvement in Confluence search, but I have yet to see a well maintained instance where this was even a medium issue. Search aside, any tool requires maintenance and tending.

So how do we get from conflagration to confluence?

First, read all that stuff above. Yes, again. Start there. Seriously, it has to be done and if you are reading this I always encourage the “if it has to be, it has to be me” approach to life. If you don’t or can’t own it, find someone who does, can, and/or will. And then HELP them. Find more people from across your organization, diversity matters, get people from various departments and form your first steering committee, governance team, Confluence Club, whatever. Start simply, and let this be an evolutionary process. Start by adopting some basics as defined above, pick one template, anything, that gets used across the organization and customize it. Then show team leads how to customize it for their teams.

Continue developing your Confluence Club and adopting standards until you have enough momentum to seek and gain a sponsor in your organization who can help drive change across the company. Seriously, it took me about 3 months of effort until people started to notice that things were running more smoothly and starting to look ‘better.’ From here, it may not always be smooth sailing, but you should have a pretty good direction to follow and enough momentum to keep things moving.

Then pick a day, start communicating (using Confluence) and ensure that all new documents created will follow the standards you’ve laid out with the team. Now you can set about to put the house fully in order.

Cleanup in Confluence can be really easy or really hard, it totally depends on what you’ve got. I’ll tell you that I have literally gone into a space, added a parent page called Z_’whatever’_archive and moved all the contents under it. Start from scratch. When you have to go find a page in the archive, move it out, but take the time to add the appropriate labels, ensure the content is still relevant, and use this process iteratively to get your wiki back in top form. Alternatively, create a new version of the page with the template.

If that, rather drastic, approach won’t work for you, then spend some time with the Space owners and help them (sensing a theme?) get their space squared away. This is a team sport!

Also, consider a more refined approach using an addon, like Archiving plugin for Confluence. Again, use the team to establish guidelines for what needs to be reviewed, when it will start being reviewed and how often it needs a refresh then let the tool tell everyone what needs to happen and when it needs to happen.

In case you need more ammunition, someone doing this consulting thing far longer than me recently called KM the first step in improving service while controlling costs and spelled out the following steps to implement it properly[9] :

  • Progress iteratively – don’t run an enormous project to codify huge amounts of knowledge, taking months or even years before any value is created. Identify one or two pieces of knowledge that will be immediately useful and make sure that service desk agents can find them when they are needed. Once you have confirmed that this knowledge is valuable, you can start to build up a knowledge base a bit at a time, creating additional knowledge and measuring its impact, and updating knowledge that has already been created, or deleting it if it is no longer appropriate. Once you have enough content, the next step is to think about how to create direct access for users, via a self-service portal.
  • Keep it simple – you may need a huge complex knowledge base at some time in the future, but the place to start is with something inexpensive and simple that you can create quickly, that is immediately useful, and that you can then build on. This will create value; and by measuring and reporting this value you can help justify a more comprehensive solution.What’s in a page, revisited.
  • Focus on value – think about knowledge in terms of the value it creates. This will help you to avoid an implementation that drives creation and management of knowledge that nobody uses. Knowledge only has value when someone uses it, so you should measure how often each piece of knowledge is used, and how well it resolves the problem that prompted its use. Use this data to encourage and reward people who create the most useful knowledge.
  • Design for experience – think about the experience that users will have when they consume knowledge. Try to provide knowledge in a variety of formats (audio, video, text, diagrams, etc.) and at various levels (expert, technical and basic) so that users can make best use of it. Engage users early in any knowledge management project to ensure that the knowledge will meet their needs and expectations.
  • Collaborate – make use of all the resources that are available to you when creating and reviewing knowledge, so you can be confident that your content is of the best possible quality. You should include service desk agents, level 1 and level 2 support people, as well as vendors, customers and users, to ensure that the knowledge works well for the target audience.[9]

Time to focus in on some specifics. We’ve talked about what you can do with Confluence, how you should go about socializing the what, and who should be leading the charge on how. Let’s take a look at some specific ways to help Confluence help us.

I’m a user baby…

Click on your picture in the upper right corner and let’s explore.

We all need personal space

How To Use Your Personal Space

You are the Ruler of this Domain. It’s yours… no really, all you! Since your Personal Space is, well… personal, it can take any form you like. I’m going to list below a few behaviors that I generally suggest.Sandbox: If you want to try something out and don’t have access to a test environment, this area is essentially a “Space” so have at it here. Try some macro’s, mock up template changesDrafts: You know that thing that your boss’s boss is waiting for? That really critical document that you don’t want people to see until it’s done? Make it here then Move it.

I like to move it, move it…

Find the Tools Menu at the top right of the page.

confluence_greatness_like_it

To Do List: Use the Task List macro confluence_greatness_task_macro  and add a personal To Do List.

Anything else you think of. Have fun!
PS: If you’re admin’s haven’t enabled Personal Spaces, encourage them to do so. Really, wouldn’t it be better for you to practice outside of team or product spaces? How can you be a better user if you don’t have a place to practice. Then make them read this.

Profile

In the Profile Tab you can update your personal information by clicking the “Edit Profile” button in the upper right corner.

Admin Note
There are some great plugins for enhancing and using the information in the User Profile in Confluence.

confluence_greatness_mitch

Other menu options

Submenu Name
Explanation
 Tasks Displays a list of all tasks assigned to you throughout your Confluence instance.
Saved for later Displays a list of all ‘Saved’ spaces throughout Confluence so you can manage your favourites.
Watches Displays a list of all ‘Watched’ content throughout Confluence so you can manage your watches.
 Drafts Didn’t have time to finish that page before you left? Power went out? Laptop ran out of juice? No worries, your pages ‘should’ be safely saved here.
 Network This is generally the most underutilized feature of Confluence. Think about it as ‘Facebook’ for work. You can follow people who work for you (monitoring), who work with you (knowledge transfer, collaboration), or your customers. Either way, along with the summary emails, it is a nice feature for staying on top of projects.

Settings

Click the “Edit” button to change these. Keyboard shortcuts should be enabled and if you are unfamiliar with what those are, click on the in the menu bar next to the Quick Search and select keyboard shortcuts.

Email

confluence_greatness_email

Again, use the “Edit” button to make changes.

Autowatch: This one is very subjective, in general it is not a bad idea for a user who:

  • Works on the same project all the time.
  • Only works on a few issues at a time.
  • Is not a Project Manager, Team Lead, Scrum Master, Product Owner, or any other role that requires you to move frequently and far within the Confluence instance. If you are in this group, please Disable Autowatch.

Daily and Recommended Updates are very useful in a diverse environment. Confluence will attempt to use the areas with your “fingerprints” to identify content changes that you might be interested in. I’d recommend enabling these for most users and being patient for a few months to see what the results look like for you.

Show Changed Content is also very useful as you’ll be able to see the changes made to content in the email notification. Faster than going to the site and pulling up the old version.

Confluence search and CQL

I’m always a fan of leveraging your tool to the max before you start looking into extensibility. So we’ll cover quite a bit of built-in functionality, but I want to specifically mention Favorites, Watching, Tasks, and the Notification Tray. Using these wisely can improve your ability to find content that you care most about. There’s really no silver bullet with these, but they do afford users the ability to develop their own system for what’s a favorite (any space/page that you go to daily), which docs to watch (anything that is actively being developed or that you access once a week or require as a job guide), using tasks (don’t overdo it, please), and that will drive what goes in the tray. I will point out that Tasks should have some guidelines at least at the team level or you’ll end up with 1.21 incomplete gigatasks across your instance.

Search structure

Well structured searches, even in quick search, can make life easier, but the search facilities of Confluence aren’t quite as apparent as Jira.

Did you know that Confluence uses field based search like Jira does? Yep, that’s the core of the Confluence Query Language (CQL). You can see the full field list in the Confluence documentation, but the most useful are generally title, labelText, and modified[10].

Once you’ve familiarized yourself with which Lucene fields to use, it’s time to check out how to structure a Confluence search.

Conjunction junction

Operators work in Confluence just like Jira. And, Or, Not, -(exclude)

Quick search will probably ignore operators as text, even in closed quotes.

Have AND Dinner or Have Dinner will yield the same results.

Confluence search syntax

You’ll need to reference Atlassian’s Documentation on this topic as it is way to massive to cover everything here. Just know that Quick Search is just that, it’s quick, but not entirely overwhelming. If this were the extent of the Confluence search experience, it’d be no wonder that everyone hated it.

In quick search to get better results, you’d have to go and learn all those parts we just reviewed and enter something like this in quick search: labelText:how-to AND Topic_that_you_know_exists or (confluence or jira) and add-on.

LPT
If you find that you or your users are doing frequent deep searches or the Quick Search is just not cutting it, then do everyone a favor and add a shortcut to the full search in the Application Navigator (or somewhere convenient).confluence_greatness_lptconfluence_greatness_search

CQL

Currently, CQL Search feels like it is primarily geared towards add-on developers (but check out this link anyway, really, do it), the functionality itself does live (hide) within Confluence, so let’s take a look at how to use it.

At this point, I’m assuming that most people aren’t able to take advantage of CQL due it being fairly new, but hopefully that changes soon.

It’s not too different from Jira Basic JQL search.

confluence_greatness_cql

You can add filters to the bottom here (no, you can’t save them like Jira filters). You can actually stack filters too. Add-ons may add some options for you as well. Again, review the Confluence docs here in order to learn what’s available, or just go try it out.

Add-ons

Given how much complaining there is around search, it would seem that there would be many options in the Atlassian Marketplace. There really aren’t as many as you’d think. I’ve linked the search here and added a few below that I’m familiar with.

I’ve used Brikit’s Targeted Search for a specific customer and it is helpful. Look for a new version mid-February (Happy Valentine’s Day) that will contain a new feature we worked with them to develop.

It will allow you to hijack the Quick Search and constrain default searches to the current space, other spaces in the same space category, and also will only search page titles. I believe these parameters will be configurable so you’ll be able to mix and match to make Quick Search more helpful.

Search assisting macros

https://confluence.atlassian.com/doc/children-display-macro-139501.html
https://confluence.atlassian.com/doc/content-by-label-macro-145566.html
https://confluence.atlassian.com/doc/content-by-user-macro-182682080.html
https://confluence.atlassian.com/doc/content-report-table-macro-317194676.html
https://confluence.atlassian.com/doc/labels-list-macro-180846844.html
https://confluence.atlassian.com/doc/livesearch-macro-163415902.html
https://confluence.atlassian.com/doc/page-index-macro-182682092.html
https://confluence.atlassian.com/doc/page-properties-report-macro-186089616.html
https://confluence.atlassian.com/doc/page-tree-macro-163414255.html
https://confluence.atlassian.com/doc/page-tree-search-macro-163938353.html
https://confluence.atlassian.com/doc/popular-labels-macro-168003614.html
https://confluence.atlassian.com/doc/recently-updated-dashboard-macro-169607931.html
https://confluence.atlassian.com/doc/recently-updated-macro-139519.html
https://confluence.atlassian.com/doc/recently-used-labels-macro-145571.html
https://confluence.atlassian.com/doc/related-labels-macro-145560.html
https://confluence.atlassian.com/doc/search-results-macro-139511.html
https://confluence.atlassian.com/doc/table-of-contents-macro-182682099.html

Space home example

Finally, I was asked to provide you with some guidance on building good pages. Here are a couple of examples and I’ll remind you about the chili reference above.

confluence_greatness_kb_home_page

Child page example

confluence_greatness_page_sample

References

  1. https://en.wikipedia.org/wiki/Knowledge_management
  2. Girard, John P.; Girard, JoAnn L. (2015). “Defining knowledge management: Toward an applied compendium” (PDF). Online Journal of Applied Knowledge Management3 (1): 1–20.
  3. “Introduction to Knowledge Management”www.unc.edu. University of North Carolina at Chapel Hill. Archived from the original on March 19, 2007. Retrieved 11 September2014.
  4. Addicot, Rachael; McGivern, Gerry; Ferlie, Ewan (2006). “Networks, Organizational Learning and Knowledge Management: NHS Cancer Networks”. Public Money & Management26(2): 87–94. doi:10.1111/j.1467-9302.2006.00506.x
  5. Gupta, Jatinder; Sharma, Sushil (2004). Creating Knowledge Based Organizations. Boston: Idea Group Publishing. ISBN 1-59140-163-1.
  6. Maier, R. (2007). Knowledge Management Systems: Information And Communication Technologies for Knowledge Management (3rd edition). Berlin: Springer.
  7. Sanchez, R. (1996). Strategic Learning and Knowledge Management. Chichester: Wiley.
  8. Fitzell, S. (2014). Better Search for Your Knowledge Management. https://qsensei.com/
  9. Rand, S. (2016). Service Desk Improvement: Part 1. https://www.axelos.com/news/blogs/january-2017/service-desk-improvement-part-1
  10. Atlassian. https://confluence.atlassian.com/conf510/confluence-search-fields-829077817.html
Tagged with: , — Posted in Atlassian

Leave a Reply