Knowledge Base Building Blocks

[#1]

After creating a few Confluence-based knowledge bases, I thought I'd create my first article and share what I see as the key building blocks to building a knowledge base. I'm very interested to see if others have different ideas for what is required, or if there are improvements for how I can improve my own approach.

Enthusiasm and purpose: Without knowing how receptive your audience is (including your fellow co-authors), you might struggle to get your knowledge base off the ground. Understand the value -- the why -- behind what the knowledge base will bring to your organisation, and identify the concerns that people may have. Be prepared for the knowledge base to take some time to bed in to the way your organisation works. Your enthusiasm, coupled with a purpose and an understanding of what motivates people will help you, as will finding like-minded people who want to contribute to a KB. Bring people into the fold and seek their ideas; consider creating a working group (or community) for documentation where you all strive to make some form of improvements to the standards every x weeks/months.

Structure it well, name it better: There's no hard-and-fast rule for when something should be in it's own space or not. We go on a combination of complexity and target audience to determine whether something falls under a generic KB space or if it needs to be its own space. You might find that this changes over time as your KB grows. Just be clear with people what the current rules are. And while it's important to have clarity on where something should belong (e.g. avoiding silos of knowledge that end up duplicating each-other), don't overlook how pages are named...

From my experience, the most overlooked part of a Confluence KB is the page naming convention. Pages that are ambiguous in name will be hard to find, so you should always consider how someone would search for what you've written. Confluence is a wiki, and we're all familiar with wikis (thanks Wikipedia!), so seek inspiration from this. We are much more comfortable with searching wikis for content than we are using a menu tree, and this should be the same for your knowledge base. You can improve the searchability of content by avoiding ambiguous naming (e.g. don't call a page "Access Request" if its about how to get access to your company's Jira; call it "Jira Access Request"). Encourage people to use the search and set up standards (e.g. we call all our parent training pages "Application Training and How to" so that we can get people used to searching for content).

Spend time on presentation: there are a whole host of visual tools that come out-of-the-box with Confluence, and you should get to know them. A great KB article with poor presentation will be less beneficial than an adequate one with fantastic presentation.

• Page Layouts, Columns and Sections can make a huge difference in step-by-step guides, as introducing columns makes pages more compact
• Panels will let you put your content in boxes (I put each step in a process inside its own panel, with "1", "2", "3", etc as the panel headers
• Headers and the Table of Contents macro make it easier to jump through your guides
• Keep the really detailed stuff in Expand macros , especially if it's optional reading 
• Use the Multimedia macro instead of the default thumbnail for videos
• Make use of basic formatting to improve how people read your articles (e.g. highlight the key actions in your steps "Once you've completed this step, you'll want to click on 'Continue as guest'") 

A picture speaks a thousand words: pretty much all KB articles I write are full of screenshots that accompany the instructions. Guides and processes are so much easier to read if there are clear screenshots that support the step-by-step. Take your time to add valuable screenshots -- even include annotations -- because this will greatly increase the value of your content.

If you're serious, use labels: this is something I only really cottoned onto after doing my ACP Confluence Admin certification, but my goodness, how labels can help a growing KB! There are a whole load of macros that use labels, which can really help you get people to the content they need. I could write quite a lot on the subject, so instead I would encourage you to read up on the different macros that utilise labels. Set this framework up early to ensure your KB scales well. (Page Properties Report and Content by Label are examples of label-using macros that we use heavily in our KB.)

Bring it all together with Templates: you'll increase the readability of your KB if your articles follow a similar structure. Templates are a great asset for this, as you can give people the starting point when creating KB articles, which will save time and give a consistent look and feel to your KB.

Create methodologies: This one is a case for not seeing the tree for the woods. I've created KBs before -- Templates and all -- only to have people not follow the format because they don't know where to start. I've found that documenting the documentation methodologies (as bizarre as it sounds) is critical to the success of these initiatives. That and taking the time to help people out.

Connect with your Jira (if you're self-serve): if you've made use of a Jira Service Desk portal, then you should read up on how you can connect this to your Confluence KB as this can really help your customer.

Seek continued feedback: finally, ask people in your audience how helpful they find your KB; understand what works and doesn't work. Maybe even reach out externally to see what other people think of your approach to building KBs...(!)

Hopefully you'll find some of this useful, and I'd love to hear what people's thoughts are on these Knowledge Base Building Blocks -- anything I'm missing; anything you'd do differently?

[Bridget]

Amazing first Article!! This guide is so comprehensive and useful. 

[Jennifer Drewry]

Terrific article and great take-aways especially being mindful of naming conventions. I especially appreciated the reminder that Confluence is a wiki; we must consider how people search and keep in mind KISS (Keep It Simple Sam)  ;)