nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Building a knowledge base: What are the best practices for Confluence Customer KB?

MadelineBarr

We have Confluence server and JIRA Service Desk. The Service Desk team has been building a KB for themselves for IT support.

We would like to build an IT support KB for the public using Confluence to link to JIRA SD.

I'm looking for ideas and best practises.

Do you keep your public KB and tech support KB as separate spaces?
I would assume that these KBs sometimes share information. How do you handle that?
- Do you use the page include macro?
- Is this handled in your search bar to check both spaces?
- Is it in the process that the Service Desk it expected to check both KBs?
- Permissions?
- Something else?
Do you use the standard KB template that comes with Confluence or do you have your own? If your own, how is it different?
Who writes your public KB articles?
What process do you have in place for pages to become public?

We're concerned that most of the staff will write too technical for the general public. We're also realize we need some sort of standards.

I would love to hear how you've handled public KB articles or issues you have.

Comments

Dr Charlie

A single Jira Service Desk project can only link to a single Knowledge Base (aka Confluence Space).

In order for both agents and customers within this project to access Knowledge Base articles, you need to set permissions on Knowledge Base articles that you do not want the customer to see.

Presuming you are opting for the free access for customers to the KB via the portal, you can hide 'agent only' pages by limiting to either the jira-servicedesk-users group (where confluence and jira are sharing a user directory, or confluence is connected to Jira's), or another group which the agents are members of.

Have found the How-To and Troubleshooting templates to work very well in practice, although you can make your own or copy and adapt these to meet your requirements.

If you wish for an approval process before an article is published, you can look at using Comala Workflows to provide this functionality - https://marketplace.atlassian.com/plugins/com.comalatech.workflow/server/overview

Hope this helps!

MadelineBarr

@Dr Charlie this is all very good information.

Pointing out that Jira SD can only link to a single KB space is important. I should have meantioned that our "agents" also use Confluence on a regular basis for other tasks and have access to many spaces. I don't think we are going to user the free access or customers to the KB, we'll use our existing Confluence instance. So having the options to have agent articles in a different, restricted space would you use it or keep the documentation together?

I would like to use the templates provided but I'm curious to how others feel they need to be modified. Good to hear that I'm not the only one who likes the delivered templates.

Thanks for the link to the approval/workflow add-on. I will take a look.

E.L. Fridge

Here's how we approach this issue at UWF. We have a public knowledge base that is open to all, even anonymous users. We give anyone access because there are lots of documents here relating to applying to the university, registering for classes, etc. that people need to access before even getting UWF login credentials. There is, of course, a lot of technical support related content here but it's not exclusive to this. This content is written by help desk staff and BPL authors (see below).

Our main support service desk is connected to this space. As Dr. Charlie pointed out, there can only be one link to a space from a service desk project. It's possible to add label filters at this point if you want to restrict the content being offered to the users in the service desk forms.

We also maintain a separate space called the business process library (BPL) where specially trained faculty and staff can document university business processes. This information is restricted to users with a login, although sections of the BPL are restricted to certain groups if there is a special need for security. This is a shared space for the whole campus, because many processes are cross-cutting concerns. The help desk documents many of the campus applications in this space. We often share permalinks to this content in responses to customers, but also share links to the public space.

For sharing content, we have a separate spaces for includes that host common fragments: one for login-required content and another for public. These are included into the appropriate spaces using the excerpt macro or include page macro.

Our help desk also maintains an internal KB just for their staff. This is an internal space where help desk procedures, canned responses, and internal FAQs are stored to specifically help our customer support staff as they field questions. An example of a document here would be steps to join a computer to the domain, or procedures to deal with malware. They do use the built-in templates but aren't restricted to that exclusively. It really depends on the content being written. They have their own internal review process where managers can watch and vet new content being created, and they often assign tasks to staff to keep this space up to date.

As far as items being approved for release, we take more of a wiki approach to content in the public and BPL spaces. Certain people who consider themselves interested parties for an area of one of these spaces will watch a page and it's children, so they will get emails if a change happens. Anyone who has been through our training process is free to document information as long as they follow the procedures we teach. Content will inevitably become stale, links will go bad, so it's up to the community and to some extent our admins and documentation team here to do some wiki "gardening" and fix issues as they arise.

Alexander Bondarev_x6gjf3

@E.L. Fridge , thank you for answer!

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

confluence

education