Troubleshooting article template

by Atlassian

Document common problems and how to solve them

Use template
Troubleshooting article template

Help customers work through common problems and find solutions on their own by writing troubleshooting articles. Our troubleshooting article template gives you the structure you need to articulate the issue, detail the solution, and display related articles (which you can do automatically using labels and the content-by-label macro to keep track of related articles). Teach them to fish and give your support team more time to handle more complex tasks.

How to use the troubleshooting article template

Step 1. Describe the problem

It’s tempting to dive right into the solution with an article like this, but describing the problem is a really important part of writing effective content. Readers need to be able to tell if your article speaks to the problems they’re dealing with. Think about how your audience is experiencing this problem and explain the problem using terminology and examples that are relevant to those experiences.

Step 2. Provide a step-by-step solution

Once you’ve described the problem, it’s time to explain how to fix it. Using a numbered list, write out a step-by-step solution. Use terms that readers will know and understand, and work through one step at a time. Where possible, illustrate steps with pictures. That way, people reading your article know what things should look like at each step along the way. If there’s more than one possible solution, your best bet is to stick to the most common solution in your write-up. If you really think you need to give people more options, you can use an expand to create a collapsible panel where other solutions can go.

Step 2. Provide a step-by-step solution

Step 3. Display related articles

Sometimes, you come across an article about a problem that’s similar to yours, but not quite the same. And sometimes, knowing more about how something works can help you prevent problems later on. By applying labels to your troubleshooting articles and using the content by label macro (already included in this template), you can automatically display related articles and pages. Just make sure you use the same label for all related pages.

Atlassian is an enterprise software company that develops products for software developers, project managers, and content management.

  • AWS architecture diagram


    AWS architecture diagram

    Visualize your infrastructure to better identify weaknesses and pinpoint places for refinement.

    Use template Learn more
  • Design your ideal workweek


    Design your ideal workweek

    Provide step-by-step guidance for completing a task.

    Use template Learn more
  • DevOps runbook


    DevOps runbook

    Prepare your operations team to quickly respond to system alerts and outages.

    Use template Learn more