Write and share articles

Serving customers with a knowledge base

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

A knowledge base is a collection of articles that help your customers with their requests. It's there even when you're on holiday, working on other requests, or have gone home for the day.

Here are some reasons you might write articles:

  • If you get a lot of similar requests, such as "How do I access office wifi?", you can write a how-to article. 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 with them rather than walking them through the steps in a comment.
  • If 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.
  • If you normally walk people through a series of steps to diagnose and troubleshoot a problem, such as a broken printer, you can write a troubleshooting guide. Customers can find it in the help center, or you can link it to them in a request.

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 by clicking create an article:

When you create an article, you can choose between two handy templates: How-To and Troubleshooting. The issue summary and description become the new article's title and body text. 

Agents need the Add page permission in the Confluence space to create articles. Learn more about space permissions.

Another way to create articles is to go to your service desk project, then select Knowledge base > Create article.

tip/resting Created with Sketch.

We're rolling out a new issue view for Jira Service Desk, with one consistent screen to view and edit requests. It looks a little different and some procedures have changed slightly, so take a look at our info page to see what's new and get the latest updates.

Share articles

There are three ways you can share articles with customers:

  1. Hover over an article link and select the ‘Share as comment’ button”: 
    Customers can’t read any article that has a red padlock, so sharing those will just lead to a dead end for them. It’s best to avoid that!
  2. Automatically share articles based on keywords in the request summary. Learn how.
  3. To share links to articles, go to Knowledge base from the sidebar, then select the article you want to share. Copy the Shareable URL to then share the link. When customers click the link from a request or their email, the article opens in the help center:

Automatically share articles with comments

You can create an automation rule that shares articles based on keywords in the request summary.

To create the rule:

  1. From your service desk project, select Project settings () > Automation.
  2. Select Add rule, then Create a custom rule.
  3. Create a rule with the following properties:
    • When issue created.
    • If issue matches summary ~ <keyword>. Use Else if to add more keywords and related articles to the same rule.
    • Then add comment. Add your comment to the text box, and link the article using the format [Link name|article URL]. Make sure Comment type is set to Public.

Remember not to share the Confluence URL. Customers can only read articles in the help center, and they won't be able to read articles in Confluence.

Use keywords to help people find articles

The knowledge base suggests articles to customers and agents using keywords from request summaries. So, for the knowledge base to work properly, make sure your request types have a visible Summary field. Learn how to set up request type fields.

When agents view a request, the knowledge base suggests related articles that they can reference or share with customers. If you don't see an article that you think you should see, try changing the article title to use more keywords from the Summary.

Agents can also search and browse articles using the knowledge base in the sidebar.

Categorize articles

Keep your knowledge base organized by categorizing articles to help agents find what they need and help customers find relevant topics in the help center. For example, in a Bookings service desk, you can create categories like Booking extras and Accomodation to help organize your help topics:

To categorize articles:

  1. From your service desk project, go to Knowledge base.
  2. Click New category in the sidebar, then click Add articles.
  3. Click + next to each article you want to add to the category:

Both the categories and the articles assigned to the categories will appear listed alphabetically.  That is, unless there is a featured article - these appear first, followed by the rest of the articles in alphabetical order.

To reorder categories, just drag and drop them in the sidebar and you'll see the changes in the help center.

Feature an article

You can help customers self-serve by featuring relevant articles at the top of each help center category. This is especially useful to highlight articles that are commonly being used by customers.

To feature an article:

  1. From your service desk project, go to Knowledge base.

  2. From the sidebar, select the category where you want to feature an article.

  3. If the article isn’t already in the category, click Add article and select + next to the article you want to add.

  4. In the Featured column, turn on the article you want to feature.

The article is now featured at the top of the category in your portal.

Add an article to multiple categories

Customers looking for help in different categories may need the same article. Instead of going into each category and manually adding the same article, you can add an article to multiple categories all at once.

To add an article to multiple categories:

  1. From your service desk project, go to Knowledge base.

  2. Select the Categories column of the article you want to add to multiple categories.

  3. Use the drop-down menu or start typing the name of the category, then select the category you want to add. Repeat until you’ve added all relevant categories to the article.

  4. You can delete categories by selecting the x next to the name of an added category.

  5. Select the tick to save your changes.

Delete a category

Deleting a category removes it from the knowledge base and help center. The articles in the category aren't deleted and can still be searched for by your customer. You can either re-categorize them or leave them uncategorized.

  1. From your service desk project, go to Knowledge base.
  2. Select the category you want to delete.
  3. Select ••• > Delete category.

Suggest articles to customers

When customers search the help center, they see related articles that might help troubleshoot their problem. To make it even easier for customers to find what they need, you can suggest articles when they fill out a request:

In the above example, the request type Guest wifi account is restricted to the label wifi. The help center uses the text in the Summary field to search the knowledge base and suggest matching articles that are labeled with wifi.

To suggest articles for certain request types:

  1. From your service desk project, select Project settings () > Knowledge base.
  2. Under Auto-search on request types, choose Yes for Search KB next to the request types you want to suggest articles for.
  3. Optionally Restrict to articles with labels by selecting it for the request type and typing in the label name. To make it easy for agents who write articles to remember which label to use, we recommend using a label similar to the request form.

See how articles are performing

After you write articles, go to Reports () > Knowledge base to see how they're doing. 

Your team can use knowledge base reports to see how often an article is shared, viewed, and voted as helpful. Here's how you might use some of the reports:

  • Requests deflected: see how often customers find articles helpful.
  • Requests resolved without an article: if you see a lot of similar requests, you might need to write an article about them, or update the wording in an existing article.
  • Requests resolved with an article: if the article was shared in requests, check the comments to see if there's info or edge cases you need to add. 
Last modified on Mar 27, 2019

Was this helpful?

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