The troubleshooting guide helps the user that has a specific problem or issue with the software, to solve or perform a workaround.
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.
The following steps can be used to perform a successful troubleshooting process.
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.
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?
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.
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.
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.
Describe the problem in detail. Write the error message or error code.
Write typical conditions or cases when the problem occurs or what causes the problem.
Describe the solution in detail. Use a step by step solution approach. If no direct solution exists, describe potential work arounds.
Link related documentation files or pages e.g. in the knowledge base , user manual, matching tutorials, product features or in the operation manual.
troubleshooting / troubleshooted / troubleshoot
The following questions might be helpful to identify the root cause of a problem in a short time:
There are a lot of good troubleshooting guides available online. Here are just a few examples.
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).
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.
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.