Knowledge Bases: With Great Knowledge Comes... Sprinkles?
So previously, I shared a little into one of my recent revamps of our Knowledge Base (my baby) that I grew from almost nothing over the past 3 years. I'm not going to go into how to should manage any of your content, but instead try to share some of my developments and experiences that may be beneficial to incorporate into your own instance and how you can turn your basic vanilla Confluence Knowledge Base into, as @Kat Warner so lovely put it, a sundae with sprinkles.
I quickly learned, I can write all the articles I want on fun functionality, interesting things you can do, or recent updates as much as I want, but if users do not know your Knowledge Base exists or it's not easy to navigate, no one’s going to use it.
NAVIGATION, NAVIGATION, NAVIGATION
There are three reasons why navigation is extremely important when it comes to your articles:
- Provides easy identification that these are the answers the user is looking for,
- Provides a “bookmarking” system for your users to easily remember where to return if they have repeat issues,
- Provides a “bookmarking” system for yourself so you can easily keep track of what you have already written and what needs to be added or updated.
#3 is obviously most beneficial to us, as great knowledge comes the responsibility of keeping it up to date and actually usable. Plus, if you’re like me, and don’t like to answer people’s questions directly you can just teach them how to fish by sending them links to your articles every time your inbox is bombarded.
Now, there’s four types of Navigation I use in particular:
- Menus – We have a Knowledge Base menu we have added to the top of both Chalk and Jira so that users have an extremely easy time finding our KB articles. This is massively helpful and I highly suggest if you have a KB that touches all of your users, to look into developing a menu. There’s several add-ons that do this, but we have a smart person who was able to add it via the Custom HTML for us.
Every time a user requests information from me AND I already have a document available, I ALWAYS include both the link to the document and the route to take to find that again in the future through the menu. If you want to request help from me or my team, it’s the first link! - Confluence AND Space Landing Pages – I include quick links to a lot of resources on our main Confluence / Chalk landing page in addition to repeating a lot of my links on the landing pages of the individual spaces themselves (you can see examples of space landing pages on my previous sprinkles post). Repeating some links in multiple locations is never a bad idea; one of my most commonly repeated links is the FAQ page. I can’t show the entire Chalk Landing Page off, but this is the top section where you can see I’ve provided a list of quick links for users to major spaces or pages in our Knowledge Base. Several of these names have been modified from their actual page names to grant better understanding of where the link takes you. For instance, the Request Jira, Chalk, or TestRail Assistance button takes you to our Jira & Chalk Admin Request Portal where users can submit tickets to our team to request changes.
These “buttons” are simply images I used GIMP (free open-source photoshop like program) to round off the corners on.
Another part of our landing page provides live details about our site. We have a section for outage notifications or known issues in the tools which is populated via a multiexcerpt macro (this is an add-on, out-of-the-box excerpt macro would also work for this) on another page which I update on a fairly regular basis. This allows me to update this one section of our landing page, but never actually have to update our landing page… which is fantastic, ‘cause that edit screen is a bit of a mess to work through.
I do this to provide users a quick glance at any issues that may be occurring during this time or any major changes. For instance, here you can see an issue impacting a majority of our users AND a recent update that changed how an extremely used function operates and links to the Knowledge Base articles or Troubleshooting request (in Jira) relating to those topics under the Chalk section.
I have several blogs within my Knowledge Base, which I’ll get into in a bit, and the one of them is dedicated to official notices and upgrades was given a section so our most recent essential announcements are easily available. - One of the options on both the menu and the landing page is the Search the Charter Knowledge Base option. This directs the user to what had begun as an advanced bookmarking system for myself that has become the Knowledge Base Index. I use a combination of Page Properties and Labels (I’ll get into that in a bit) to mark what articles are so that when a user navigates to the Index, they can either do a quick search, or select a popular topic or content type to browse.
- My last method of navigation I include in every space; I customize my sidebar to show a pre-defined menu in addition to my page tree. Which ends up looking something like this:
To set up a custom sidebar in your space go to Space Tools > Look and Feel and locate the Sidebar, Header, and Footer tab. Customize the following wiki markup and paste it into the Sidebar section then save! I suggest testing this out in your personal space before deploying it to your Knowledge Base. I have also included how to add a search bar into your sidebar, which I have just realized my example above is missing and now I must go fix this…
h3. [Return to Home|https://url.com]
----
{livesearch:spaceKey=@self|size=medium|placeholder=Search this space}
----
h4. [Link Text|https://url.com]
h4. [Link Text|https://url.com]
h5. [Link Text|https://url.com]
h5. [Link Text|https://url.com]
h4. [Link Text|https://url.com]
h5. [Link Text|https://url.com]
----
VERY SHORT ATTENTION SPANS
None of us have a very large attent—okay I was gonna make a SQUIRREL joke but a bird literally just landed on a feeder outside my window so… BIRB!! I’m so sad he flew away before I could take a picture, but it was a Lark Bunting (our state bird, fun fact).
There’s a couple tricks I developed to keep people engaged while still forcing them to learn and a secret ace in the hole that I’m working on that none of my users are going to expect and I’m super excited about it.
Dividing your articles up in consumable chunks is key. Divide your topics into different articles, but also put visual breakers in the articles themselves. Especially if the article is a long one. Visual breakers can include but are not limited to:
- Images or GIFs
- Line Breaks or panels (my personal favorite is to use a panel colored blue with white panels inside as “sections” so the blue breaks up the white, like you see in my FAQ example below)
- TOCs for users to easily jump to required sections if they’re a repeat visitor
- Use your real-estate saving macros like tabs, expands, and dialogs (Note the expanding sections for each question in the FAQ example below—see suggested add-ons for more info)
- A little color can really spice up a page. I suggest identifying your company’s official color palette (I’ve gotten to the point that I have the hexcodes of our primary like, five colors memorized ‘cause I use the same color palette for everything).
- Bulleted lists where possible (easier to consume than a giant paragraph—I’m also a bit of a list-ophile… is that a word? I’m making it a word. So I probably overuse this haha)
- Bold or emphasis important notes to call them out. Using other font colors to color code notes is never a bad idea (I do it often) but I find pairing a color and bold causes the color to pop better.
- Tip or Warning message boxes (see suggested add-ons for more info)
Visual breaks in your page are different than the visual aids on your page, though one can double as both. It never hurts to add a visual to further assist getting your message across to the reader. I personally use GIFs wherever possible (thank you amazing boss for getting your hands on an amazing software for me to do this) instead of flat images when guiding users through a series of steps.
TIP: GIMP can export to GIF, so if you would like my article I wrote about creating GIFs in GIMP please let me know. It’s not the cleanest way to create GIFs, but it works. If you can get your hands on a screen recording software (Camtasia, OBS, etc.) that works significantly better.
Lastly, to keep people reading and coming back to your future articles, never forget to pull out your biggest weapon: make it fun.
Luckily, in the technophile world, most of us are in one shape or another, nerds. So I try to theme every article I write with some nerdy theme. I’m partial to Sharks and Harry Potter, but I’ve tried to include others like Star Wars, LoTR, and Terminator. It even helps keep the tedious task of writing up articles fairly entertaining.
TIP: No matter what your job is, there’s always a way to make it fun.
My super-secret ace-in-the-hole that I’m developing is a “Chalk RPG Quiz” where users will be able to test their Chalk knowledge by taking a quiz. I use Dialogs (requires Content Formatting for Confluence Add-On) to provide “paths” a user can take while answering a series of fantasy themed questions. They’ll have to protect their Vault (a restricted page) in their Castle (their space) to keep the Chalk Bridge Troll from getting to their treasure… and if they selected the steps wrong they’re treasure is gone! This is an extra credit thing I’m doing on my own time to make sure my boss isn’t aware of it. I want to see if even he can defeat the Chalk Bridge Troll!
FAQ Example:
WATCH YOUR STEP – ER SPACE!
This is more of a personal preference and very dependent on the type of content in your knowledge base but ties into the navigation piece.
Think about how you want to divide your information. If you have one topic you’re covering, maybe only stick to one space so users know there’s ONE place they should go. If you’re like me and have multiple avenues or distinct categories of information, use separate spaces for different topics or if you need a different set of watchers. For example:
- Jira & Chalk Administration Request Space – Location where users request Jira or Chalk support), and any documents related to those tasks (ie. policies, workflow or screen templates, troubleshooting notes). You would find no how-tos or information about our instance here.
- Writer’s Block Blog Space – My nerdy how-to’s specifically written to improve one’s knowledge of or quality of life within the tools. Lots of “how do I use macro X” type articles. This doubles as my “goof off” zone. All the pages in this space are either drafts restricted to my team or supplements to published blog posts.
- Atlassian Tools Announcements Blog (ATAB) – Blog specifically around announcements of the tools (ie. release notes, major known issues, the notification when we switched to 2FA). I force all Confluence users to watch this space as any announcements here will impact everyone. There are no pages in this space. I customized the sidebar for this space to show our standard knowledge base sidebar which links to my other KB spaces and nothing else. This way these users only get notified when essential articles drop.
- Atlassian User Community – similar to this Atlassian Community, but specifically within our instance. Users can post and ask questions, find technical how-tos (how to delete a space, how to manage email notifications, etc.), browse FAQs, and discover links in our add-on corner to the official documentation from vendors. No macro usage or “quality of life” articles can be found here as they all live in the Writer’s Block Blog.
- TIP: FAQs can really stimulate your Knowledge Base. My rule of thumb is if I get the same question more than twice, I add an entry to my FAQ. This also gives me a list of "canned responses" to commonly asked questions if users do end up reaching out to me anyway.
Since I use multiple spaces, I needed a way to track everything in one place, which became my Knowledge Base Index. I have a template I set up in each of my spaces (I could have used a global template, but we have too many users that could potentially add articles to our spaces that way) which contained the following:
- A hidden Page Properties macro (Confluence macro) with a table that contains the topic of the article, the category it belongs to, and the last updated date.
- A set of Labels marking the content type (ie. blog, template) and a few key buzzwords of the article.
This information then feeds into all of my navigation, landing, and index pages using either a Page Properties Report macro or Content by Label macro. My blog TOCs are Page Property Report macros in order to include the Subject Matter, since I use funky nerdy titles. I usually put the Page Properties Report inside of an Advanced Tables (Bob Swift Add-On) Table Filter macro which allows me then to provide a drop down filter for Category, as long as I keep my categories standardized. In my Knowledge Base Index when sorting by either content type or buzzword (topic), I use the Content by Label macro as all I care about are the titles of the pages based on what labels are present on the page.
TIP: There’s all sort of note I leave for myself on my pages that I leave hidden in a Hide Content macro from Bob Swift.
LET'S TALK ADD-ONS
So for the most part, everything that you see me do is possible with vanilla Confluence and one add-on. Adaptavist’s Content Formatting for Confluence (or CFFC) is a MUST HAVE for ANY Confluence instance in my opinion. This add-on opens up so many formatting possibilities. This add-on includes buttons, dialogs, alignment macros, tabs, message boxes and more. There’s about 30 macros included and is well worth it. This has become our most highly used macro set (aside from an in-house developed macro set that does some fun Jira stuff). CFFC can assist you to transform your basic document pages into beautiful webpages.
UPDATE: As of August 17, 2020 I have just learned that Content Formatting for Confluence, which I wasn't aware wasn't available for Cloud, is now available for the Cloud version of Confluence! Nice timing guys.
There are several Confluence functions and add-ons that handle page views or space statistics in some capacity, and since this is easily our most requested functionality, we’re always trying to find something that’ll work for our instance. Each add-on we tried never failed to hurt our performance. There is a Space Activity Function that didn’t work for us that may work for you. This can cause your index to skyrocket, so again, I hope you have a testing environment! Atlassian, this is my not-so-silent scream for someone to improve the Stats indexing issues!
So I know you can relate your support portal in Jira Support Desk (JSD) with your Confluence knowledge base, which to be honest, sounds amazing. Unfortunately for me, this isn’t something viable I can look into at this time. However, Atlassian has a wonderful article explaining how to set this up so if you already use JSD or are considering it and have a Knowledge Base, this is for you.
Was this helpful?
Thanks!
Heth Siemer
About this author
Business Analyst / Application Admin
Charter
Colorado
9 accepted answers
5 comments