Write and search for knowledge base articles

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Your knowledge base is there for customers, even when you're working on other requests, at home for the day, or away on holiday.

Here are some reasons you might write knowledge base articles:

  • You get a lot of similar requests. Like "How do I access office wifi?". When customers search for 'wifi' in the help center, they'll find your article. If they send you a request, you can share the article rather than walking them through the steps in a comment.
  • You're upgrading a system. You can write a step by step upgrade guide and link to it from an announcement in the help center.
  • You're troubleshooting the same issue with customers. If you normally walk people through a series of steps to diagnose and troubleshoot a problem, such as a broken printer, a troubleshooting guide will save you time.


On this page:

How to write articles

After you set up your knowledge base space, the issue view displays a panel called Related knowledge base articles:


If you don't see a relevant article, you can create a new one from the issue. You'll need the Add page permission in the Confluence space. Customers can read any article that doesn't have a red padlock. 


To create a new article:

  1. Click the create an article link. 
  2. By default, the issue summary becomes the new article's title, you can edit this.
  3. Choose either the How-To or Troubleshooting template.
  4. Follow the prompts to create the article, then Publish
  5. Check how it displays in the issue view.

Page labels are essential in knowledge base spaces. These are used to add topics to your articles, and allows your knowledge base to become self-organizing over time.

You can also create articles from the sidebar, then Knowledge base  > Create article.


How to share articles

There are two ways you can share articles with customers:

  • Hover over an article to share it as a comment on a request:

  • Share links from a knowledge base article that you access via Knowledge base in the sidebar. 

When customers click the link from a request or their email, the article opens in the help center:


How the search works

The knowledge base recommends articles to customers and agents using keywords it pulls from the Summary field of a request. 

Help Center and Customer Portal search results

When a customer types something in the search field on the Help Center or Customer Portal, the results return the following:

  • Related knowledge base articles. These help customers resolve their own issues, without needing to raise a request. 
  • Related request types. These are recommended to customers, so they know which request type to fill out based on their issue. 

Image of search results when user has typed the word Product in the search field.

Example results when a customer types "Product" in the Help Center search field


To make it even easier for customers to find what they need, you can recommend articles when they fill out a particular request type.

Image of Wifi request type and search results

Recommended articles for the Get a guest wifi account request type


In the above example, the request type is restricted to the label 'wifi'. When the customer starts typing words in the Summary field, articles in the knowledge base that have the label 'wifi' are recommended.

To recommend articles for certain request types, go to Project settings > Knowledge base > Auto-search on request types, then in the Search KB column, choose Yes:

Image of auto search on request types you see in product


You can restrict the search to articles with a certain label. To make life easier for yourself, use a label similar to the name of the request form.

You can't use labels as a way of restricting access to an article. For example, if you create a knowledge base article and add the label "display", and then create another article and don't add the label "display" – the page without the label will still display in the search. Adding labels are a way to filter related articles, not assign viewing permissions.

If you need to restrict an article so that only certain users can view it, do this through knowledge base settings and permissions.

Important things to note:

  • The knowledge base search and the request type search are independent of each other.
  • The knowledge base search will display a maximum of 3 results.
  • The request type search will display a maximum of 5 results, and:
    • The primary search picks up words that the customer is typing in the Summary field, and looks for them in the request type's Name and Description.
    • The secondary search uses JQL queries to find relevant request types based on the request's Summary field.


Issue view search results

When agents view a request, the knowledge base recommends related articles that they can reference or share with customers. Your service desk will search the Confluence space you have linked for any articles that contain keywords in the request's Summary field.

Important things to note:

  • The knowledge base search will display a maximum of 3 results.
  • The search ignores all other fields from the request (only the summary field is used).
  • Check that your request types have a visible Summary field. Read Setting up request types.
  • The search skips articles that the agent doesn't have permission to view.
  • The search and ranking follows the same rules as the Confluence search. In short, Confluence identifies all articles that contain keywords matching those in the request's Summary field, and sorts them by word frequency.
  • Agents can only share articles that the customer has permission to see.
tip/resting Created with Sketch.

Change the article title to include more keywords from the request summary field, if you don’t see an article that you think you should.

Agents can also search for articles via the Knowledge base in the project sidebar.

Last modified on Mar 5, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.