Redesigning our knowledge base

[Paul Wiggers]

Hello all!

I would like to hear how you have arranged your knowledge base!

Let me explain why.

Currently we have our knowledge base available for logged in portal customers. We have designed the page in Refined and attached several spaces to this site which present the information to our customers. It looks good and it can give the users all the information they need. However...

There are a few issues we are running into by using Refined and our current setup.

• Sign-up e-mails link back to the Atlassian JSM portal. This means that users end up in the wrong portal environment after they have signed up. They then need to close the window, and browse to our custom domain in order to continue
  
  
• We cannot link KB articles into issues from the JSM software since those links will refer to the Atlassian KB and not the the Refined website.
  
  
• Automatic translations are not available. This forces us to present the KB in English, even though our biggest customer base speaks a different language. 
  
  
• We have a lot of spaces without much of a structure.

After using this setup for a while, I am preparing to redesign it all from scratch and I am looking for inspiration.

It would be great if you can show me how your setup looks like. Here are some questions which would be very helpful if you can answer them.

1. Do you use the basic knowledge base or do you use an app? Why did you make this choice?
2. How does your spaces setup look like? Do you have different spaces for different subjects, do you have one space for everything or do you make another distinction? 
3. Do you use an open knowledge base or is it behind a login? Again, why did you make this choice?
4. How do you deal with a multi-language user base?
5. How do you handle KB article creation? Is every agent allowed to create and edit KB articles or do you have some kind of approval system in place?

I am curious to hear how you have setup your knowledge base and why. All tips and tricks are welcome.

Thanks in advance!

ps. screenshots for visual inspiration and explanation are great 

[Patrick Haley]

Hey Paul, 

Mostly commenting hear because you posted some great questions and I want to follow the thread to receive the replies (if you ever get any). 

I'll preface by saying that I don't currently use Confluence for our user-facing KB and opted for WordPress to handle some of the translation issues you brought up. Ideally we'll become a little more sophisticated and move this to Confluence, but this is how I handle all of the above: 

1. Do you use the basic knowledge base or do you use an app? Why did you make this choice?

We use a simple WordPress site using the KnowAll theme. I selected WP based on my experience and knew there would be various themes and plugins we could use. One of our requirements was making the KB only available via Google SSO for 3 different Google Workspace Enterprise accounts. We used the miniOrange SSO plugin for this. Also, users are free on WordPress which helps. 

2. How does your spaces setup look like? Do you have different spaces for different subjects, do you have one space for everything or do you make another distinction? 

I can't completely answer this since I don't currently use Spaces. Hopefully, we'll get there! However, we do use a combination of Confluence and WordPress. Primary end-users access the WordPress based KB with all of the videos and how-to content. 

Internal software documentation is handled in Confluence. Our devs and key support team have access to this.

We have another confluence space that's more advanced support-troubleshooting articles that we don't want to appear in the search for the end-user KB. It's more instructional how-to content for super users and tier 1 support. 

3. Do you use an open knowledge base or is it behind a login? Again, why did you make this choice?

All Confluence spaces are on tight lock-down because they contain confidential software documentation and sensitive support routines. Our end-user KB in WordPress requires Google SSO. This is because we're a franchise organization and our learning content is proprietary. It's the secret sauce that we don't want out in the world. 

4. How do you deal with a multi-language user base?

We only operate in the US, Australia, and New Zealand. However, in our business that are lots of industry-specific words that need to be translated; e.g. claim and draw, change order and variation, etc. We created a dictionary of sorts that's essentially a table of what each word is in US, AU, and NZ. We use the TranslatePress plugin for WordPress which detects where users are accessing the KB from based on IP address or direct URL. We translated all of the words in the dictionary and renders them for each user. It's not perfect, but 99% of our content is the same. I think it would actually work better for KB's that are truly multilingual. This is a pretty complex one so let me know if you have any other questions on it. 

5. How do you handle KB article creation? Is every agent allowed to create and edit KB articles or do you have some kind of approval system in place?

Only trusted support staff are allowed to create/edit content on our KB. I'm a stickler for making sure KB content is of high quality and consistent. People kind of suck at writing so I created a style guide to provide direction for new editors. I spend time training them how to log in and start editing. Then we collaborate and edit a few of their new articles in Google Docs until I'm comfortable with them adding new content. This works for a small team, but probably isn't possible if your contributor base is large or in different languages. Send me an email at patrick.haley@gjgardner.com if you want a copy of the style guide. 

My one piece of advice on contribution is to set the default language of your KB to the primary language of your contributors. I mentioned that we use the KnowAll theme on WordPress with the TranslatePress plugin. I'm American and the US will be our largest market eventually (it isn't currently). With TranslatePress you need to write articles in your default language, then the plugin translates them to your target languages. So we write articles in American English and they get translated to Australian and New Zealand versions. The problem for us is that most of our article contributors write in AU English. So the translations to US and NZ don't always work. I have to coach our contributors how to write in American English just so the plugin works the way I have it set up. 

I hope this helps!

Patrick