プロのようにトラブルシューティング記事を書く

About this article
By Desiree Conceicao, published July 13th, 2016

Save time and avoid duplication

The most efficient way to help someone is to help them help themselves – and a good troubleshooting article does just that. Troubleshooting articles are a great way to document issues and provide immediate help to common or easily solved problems, letting you save your time and effort for more important endeavours.

When you first create a troubleshooting article, Confluence automatically creates an index page in your space sidebar so you can find all the troubleshooting articles within a space in one place - where they can be ordered by title, creator, or date modified.
 

tip/resting Created with Sketch.

To use the troubleshooting article template, choose the Create button from the sidebar, then select Troubleshooting article.

1. Choose a title and label

Most users will find your troubleshooting article by searching for it, so the best way to make your article easy to find for the relevant audience is to name it after the problem you're trying to solve, using the terms your users are likely to type into the search. 

If, for example, the problem you're troubleshooting is that you can't change the permissions for a page, you might call your article Unable to change Confluence page permissions/restrictions.

Add labels to your articles to make them easier to find and organize. Users can search by label, or use a Content by Label macro to generate a list of all the content tagged with a certain label. 

The troubleshooting template automatically adds a 'kb-troubleshooting-article' label to your document, but you can also label your article with the topics it covers or with any other categories that it falls into. There is no limit to the number of labels you can add, or to the label combinations you can search for.



2. Describe the problem and symptoms

Describe the problem as the user would experience it, and be as clear and unambiguous as possible. Even if you think your title is self-explanatory, your readers might not be certain that it's the same problem they're experiencing unless you give them more details.

For the above example, you could say: "When I'm on a Confluence page and click the Restrictions padlock icon, the names in the dialog box are greyed-out and it won't let me add or change any of the permissions."

3. Possible causes and solutions

If, as in the example above, there's only cause – that is, the user doesn't have permission to change anyone else's permissions – you can jump straight into the cause and possible solutions.

For more complex problems that have multiple causes, each with their own possible solutions, put these in a table or have separate sections for each. In this case, use a Table of Contents macro to make it easier for your readers to navigate through the information.

  • When you're writing this section, ensure you keep it simple. Use subheadings and bullet points where possible, so it's easy to follow along.
  • Break every step down into its components. Instead of saying, for example, "Check who the space admin is", say "Choose Spaces > Space directory in the Confluence header, then choose the Space Details icon beside a space. The space admin will be listed there."
  • Try to avoid using jargon. If you can't avoid it, try either defining it in a Panel macro or Info macro, or hyperlinking those terms to another page with more information about them.
  • Use screenshots, diagrams, and visuals – it makes your article easier to read, and can be used to make some of your steps clearer.

4. Related content 

Make your article even more useful by adding some related content at the end.

  • Similar or related issues – Help your users find similar or related issues by clicking on the Content by Label macro at the bottom of your page and editing it to choose the appropriate topic labels.
  • Tips and tricks – Got any ideas to help prevent the problem you tackled from happening again? Share some tips and tricks with your user with a Tip macro.
  • If you use any JIRA application – Add a JIRA Issues macro to your troubleshooting article to provide quick access to known issues. This has the added advantage of automatically updating when an issue is resolved or its status changes. 

  • If you use Questions for Confluence – add a Questions list macro to troubleshooting articles, to highlight the top questions with the same topic as the article, and an Ask a Question button to the knowledge base homepage. 



tip/resting Created with Sketch.

Pro tip

When you create your first troubleshooting article in Confluence you'll a page properties panel at the bottom of the page. The Page Properties macro works in conjunction with the Page Properties Report macro to let you create a summary page that pulls in information from multiple pages.

You can choose what information this captures, and can put any fields into this macro. This is especially useful if, for example, you want to create one page for all the troubleshooting articles across your organization.

5. After publishing

Once you've published your article and shared with the rest of your team, users can use inline comments if they need further clarification or help with any of the information you've shared.

When you've dealt with an inline comment, click Resolve and it'll disappear from the page.

You can always find resolved comments again under the more actions menu  to help you track what your readers need additional help with.


Bonus: Customize the troubleshooting template to fit your team's workflow

You can edit the troubleshooting template at any time and tailor it to fit your team's specific needs. If you want to edit the template for your specific team or project, go to the Space Tools menu and select Content ToolsUnder the Templates option you can view and edit any of the templates included. If you're a site admin you can also edit the global template to customize it company-wide.


At a glance: what did you just learn?

    • Troubleshooting Article template: It does most of the work for you. Follow the page outline, and fill in content that makes sense for your specific requirement.
    • Troubleshooting Article Index: Once you've created a few troubleshooting pages, you can see all the high level details at a glance on an index page that Confluence automatically creates when you use the template.
    • Page Properties macroThis macro makes it possible to create a reporting page across all your troubleshooting articles. When using the template, it will be included on your page.
    • Content by Label macro: This is used to display lists of pages, blog posts, or attachments that have particular labels.  
    • Table of contents macro: Creates a table of contents based on the page headings.
    • Info, Tip, Note and Warning macros: Allows you to highlight important information.
    • JIRA Issues macro: Create and display dynamically updating JIRA issues on your Confluence page.
    • Customizing templatesYou can edit any of the templates that come included in Confluence to fit your specific workflow.


 

Hungry for more?

Watch the blogs in this space to get notified when new tips articles like this are posted.

 Find this page helpful? Share the love on Twitter or LinkedIn

Powered by Confluence and Scroll Viewport.