According to Wikipedia, the definition of Troubleshooting is that “Troubleshooting is a form of problem solving, often applied to repair failed products or processes on a machine or a system“.

This is a multi-step process that starts with a few basic questions, collecting and researching various circumstances and specific conditions of the software or application to identify the symptoms. Eliminating non-relevant issues can be used the identify the potential causes of the problem.

When the problem is identified, one or multiple solutions needs to be defined or created. In case no solution is possible, a workaround is defined.

For typical problems that occur multiple times – by different users or customers, or on a weekly-monthly basis – a specific troubleshooting documentation should be created for this issue.

How to perform a troubleshooting session?

The following steps can be used to perform a successful troubleshooting process.

The 4-step guide of a successful troubleshooting session to create the Troubleshooting Guide

Step 1: understand the problem

Understand what the user wants to achieve and what the expected outcome is.

Let the user describe the problem in her/his words. Get screenshots or perform a remote session (/e.g. using Teamviewer or another remote access tool). You must be able to exactly describe the problem where it occurs, and in best case reproduce it.

Step 2: identify the circumstances and problems causing the issue

To analyze the root cause of the issue, you can use typical questions at the end of this article. If it is not clear, check with your colleagues from support or development team. Is there a similar problem that might be helpful?

Step 3: define a solution or a workaround

If this is a UX problem – e.g. user does not understand the screen, forgot a step or configure a specific setting, check the product documentation if this is unclear/missing, and improve.

If this is a bug that can be resolved/fixed, fill a bug report and check with product manager and dev team.

If no solution is possible or no fix is being developed, try to find a workaround how the user can circumvent the issue and get the desired result.

Step 4: document the outcome

Finally the issue and the solution should be documented in a troubleshooting document. This is described in the next section. It might also be added to the sections of “known issues” and “frequently asked questions” on the documentation system.

How to create a troubleshooting article?

Typical user problems and issues that might be caused by UI/UX glitches or a bug in the web application should be documented in a troubleshooting article e.g. on the knowledge base system or the documentation software. Typical common issues might be combined in a specific troubleshooting guides section.

The following sections and elements should be created and filled and can be used as a troubleshooting article template.

Description of the problem

Describe the problem in detail. Write the error message or error code.

How to identify the problem / causes of the problem

Write typical conditions or cases when the problem occurs or what causes the problem.

Solution

Describe the solution in detail. Use a step by step solution approach. If no direct solution exists, describe potential work arounds.

What are typical questions of a troubleshooting guide?

troubleshooting / troubleshooted / troubleshoot

The following questions might be helpful to identify the root cause of a problem in a short time:

When did the issue start?
Did the product ever work without this error for the particular task?
What was the last thing you did before the issue started?
Does this issue happen on all devices (e.g. other computer, smartphone, tablet)?
Does this issue also happen for a colleague or other user?
Which component of the product is affected?
Have the default settings been changed by the user? Are they affecting the software to cause the issue?

What are good troubleshooting guide examples?

There are a lot of good troubleshooting guides available online. Here are just a few examples.

AWS Troubleshooting

The Amazon Web Services are a very complex ecosystem that might very soon lead to problems – caused e.g. by operating system, specific settings, hard drive, maintenance, traffic sources, equipment, network, firewall, connectivity issue and other common problems.

The troubleshooting documentation and guides are grouped by product (e.g. Amazon EC2, AWS CloudFormation, AWS Elastic Beanstalk) and further divided into product-specific docs (e.g. Amazon EC2 virtual computer instances are grouped into Troubleshooting Windows instances, Troubleshooting VM Import/Export).

URL: https://docs.aws.amazon.com/awssupport/latest/user/troubleshooting.html

Microsoft products troubleshooting

The number of products created and sold by Microsoft are quite huge. So the troubleshooting is grouped by product (e.g. Windows operating system, .NET development ecosystem, Visual Studio development environment, Azure cloud provider and infrastructure, Microsoft Dynamics 365 ERP and CRM systems, Microsoft Office).

For example, the Microsoft Office troubleshooting landing page targets admins and IT Professionals, splits by product as Office 365 (cloud) and Office (on-premise, installed office software on a computer), Microsoft Teams, Sharepoint, Exchange, …) and is further divided into specific section as e.g. Office 365 Enterprise, or Office 365 Security.

The Office products troubleshooting landing page lists the office products troubleshooting articles and links to other sections in the Office support center as e.g. known issues, fixes for office installation or activation issues, troubleshooting of installing Office. At the end it links to the Q&A, Microsoft Community and lists recommended content.

UR: https://docs.microsoft.com/en-us/troubleshoot/

Need help in troubleshooting?

If you have a question or need some more information how perform troubleshooting or create a great troubleshooting guide, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.

This page is part of the comprehensive list of documentation types.
[Continue reading]