Tackle the impossible with Atlassian. Catch up on sessions from Team '23, now available on demand. Watch now →
Troubleshooting article template
Document common problems and how to solve them
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 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.
More software development / IT templates View all
AWS architecture diagram
Visualize your infrastructure to better identify weaknesses and pinpoint places for refinement.
Design your ideal workweek
Provide step-by-step guidance for completing a task.
Prepare your operations team to quickly respond to system alerts and outages.