No matter how much time, effort, and resources you and your team put into creating a SaaS product, it will never be perfect.
It can be excellent—but not perfect.
We stress this because coming to terms with that reality is essential for creating a must-have document for your product—a troubleshooting guide.
Writing a great troubleshooting guide is challenging. Like the product it’s for, it will most likely never be entirely flawless.
However, if you follow some crucial steps while writing it, it can be a resource that your users will be thankful for.
Let’s start with the first step in the process.
Prepare a List of Common Problems
Software products consist of many elements, features, and thousands and thousands of lines of code underneath it all.
With so many components interacting with each other, it’s no wonder that problems can occur.
Likewise, troubleshooting guides can’t be expected to contain every possible problem and solution to them.
One of the reasons is that software products change, evolve, and update over time, so the list of issues can’t ever be final.
That’s why you should list the most common problems users face and make a troubleshooting guide based on it.
When you do that, you’ll end up with a guide like the one from Slack.
Their troubleshooting guide for connection issues, which you can see above, is essentially a list of the most common connectivity problems.
An important factor to note when preparing a list of common issues is that you should categorize and organize them logically.
For instance, in the example above, Slack did that by grouping connection problems.
On the other hand, Amazon Web Services organized its troubleshooting guide into 17 different categories.
Regardless of whether your list of common problems has five items or 55, you first need to know what the most common problems are to make that list and to create a troubleshooting guide like those we’ve shown you above.
You can gather data about recurring issues with your SaaS product by analyzing error logs.
As Jonathan DeVore, an employee training specialist, points out, a good error log will provide you with the following information about the issues:
- Who did it happen to?
- Where did it happen?
- When did it happen?
- What variables were involved?
Therefore, analyzing error logs can provide valuable data about the issues but also give you the most useful information for the list you’re creating—which problems occur the most.
Determine the Cause of the Problem
The next fundamental step of writing a troubleshooting guide is to find out what is causing the problems you’ve put on the list.
It goes without saying that a troubleshooting guide should provide a user with solutions to your SaaS product’s problems.
In other words, it’s not simply a list of problems; it’s also a list of solutions. And to know the solution to a particular problem, you first need to understand what causes it.
One of the ways you can find that out is by asking your users questions about the circumstances in which the problem occurs.
And it’s important to ask them because it’s unlikely that they’ll come to you on their own without an incentive.
According to Esteban Kolsky, an analyst and customer experience expert, only one out of 26 customers will voice their problems to the company. Others will simply leave.
You can ask your customers about the problems they experience in several ways.
For example, you can conduct customer surveys with tools like Typeform or SurveyMonkey.
They usually have many free templates to choose from, so you can even find a pre-made survey that fits your needs.
Whether you use customer surveys, your own analytics, or some other way of determining what’s causing the problems, you should always consider the complexity of SaaS products.
Why? Because their complex nature means that problems can have multiple causes, and that’s vital when creating a troubleshooting guide.
For instance, when you use Canva, a popular graphic design tool, you may encounter the problem of missing designs.
Luckily, the team behind Canva’s troubleshooting guide found multiple possible causes of that issue and included solutions for them.
You can see some of them below.
In total, there are six likely causes of the missing design problem, each of which has a solution in the troubleshooting guide.
Finding the cause, whether it’s one or many of them, is crucial for solving the problem and creating a comprehensive troubleshooting guide.
Provide a Step-By-Step Solution
After you find out what causes the problems in your SaaS product, it’s time to offer your users some solutions.
Solving a problem usually means the user needs to perform specific actions to get the product to work as intended.
The way you formulate your instructions for those actions is crucial in this stage of creating a troubleshooting guide.
That’s why you should write your solutions as step-by-step instructions.
They are a way to patiently and gradually guide the user from the first phases of problem-solving to the final solution itself.
Levi Olmstead, an experienced SaaS content marketer, is also a big proponent of the step-by-step approach.
The effectiveness of your step-by-step instructions depends on how you write them.
Specifically, if you want them to make completing tasks easier, be clear, and steadily guide your customer to the solution, as Olmstead describes them above, your instructions should be brief and well-structured.
For example, let’s go back to the Slack troubleshooting guide.
Take a look at their troubleshooting steps for dealing with browser errors.
There are six steps for resolving the issue, which might seem like a lot.
However, the instructions are concise and straightforward. Most steps are described in one sentence; the fourth one, which consists of three sentences, is the longest.
That’s an efficiently structured and clear guide that still provides enough details despite how brief it is.
In addition to length and structure, language is also essential for the success of your instructions.
Simply put, the users should be able to understand what they need to do.
Using plain language and avoiding technical jargon is a great way to maximize the chances of reaching the broadest possible audience.
Discord understands the importance of language, so their troubleshooting guide is written in everyday language.
As you can see above, their instructions are very descriptive and precise.
Regardless of the users’ technical background, everyone should understand what “mic or headset icon with a slash across it” means.
Step-by-step instructions with concise and simple wording and precise structure are immensely efficient in guiding the users to any solution.
But you can make your guides even more helpful with visuals. Let’s explore that further in the following section.
Add Visuals to the Article
If you want to make your troubleshooting guide even more helpful, you shouldn’t skip adding visual elements to it.
This step can raise the quality of your help resource.
Writing is the cornerstone of every troubleshooting guide; however, the visual elements can make every written instruction significantly clearer.
That’s because visuals can often convey information more efficiently than words.
As Will Fleming, the author of Technical Writing at LBCC, points out, visuals can turn something abstract into something concrete.
You can take advantage of that when writing a troubleshooting guide.
For instance, if you’re describing how to clear a browser or desktop app cache, it’s much easier to show the screenshot than to describe it using only words.
That’s what the team behind Airtable’s troubleshooting guide have done.
They use a combination of text and screenshots to describe to their users how to perform that troubleshooting step.
That way, they make instructions as clear as possible and minimize any confusion or misunderstandings regarding the instructions.
The user only needs to look at the visual and see if the situation on their screens matches the screenshot in the guide.
A step up from that is if you use annotated screenshots. You can draw the users’ attention to the specific details in your screenshots with annotations like arrows, circles, or highlights.
Below is another example from Airtable where they pointed to where the “Trash” is in the layout of their product.
It’s hard to get any clearer in your instructions than that.
However, if you have a lot of steps to cover and want to save space in your troubleshooting guide, you can use video.
It’s a convenient and easy way to show a process from start to finish without using many individual images, screenshots, and text paragraphs.
For instance, Hopin uses video in their troubleshooting guide.
The video explains how to use the Hopin platform to join video conferences.
It’s a part of the troubleshooting article which contains a lot of textual instructions, so the video also serves as a welcomed break from the reading.
Visuals can add an additional layer of quality to your troubleshooting guide, not to mention facilitate understanding even the most complex instructions. Be sure to utilize their benefits.
Include Links to Related Articles
At this point, the troubleshooting guide for your SaaS product is taking shape. It has concise and helpful step-by-step solutions for the most common problems, complemented by visuals.
Now, it’s time to connect the related troubleshooting articles.
That is a step you shouldn’t overlook because it can significantly help your users find the information they need.
The article might contain a solution to a similar problem to the one that the reader is experiencing, but not the exact one.
If the user gets stuck there, without directions to the solution they need, they could get frustrated and leave.
And if they leave your troubleshooting guide without getting help, they might also abandon your product.
Of course, you don’t want that. But there is a way to provide help even if a user lands in the wrong troubleshooting article—include links to related ones.
For example, Netflix provides instructions for when both their software and the device freeze.
However, if the consumer only experiences Netflix freezing, that is not the right help article for them.
Luckily, Netflix links to the relevant article, so the readers can quickly find the guidance they need.
Depending on the topic of the troubleshooting article, you can link to more than one related article.
That’s what Spotify does in their guide to resetting the password.
In addition to offering several solutions to the issue of not being able to reset the password, they also link to articles that can help readers to log in or deal with hackers.
The logic behind it is that users usually want to reset the password if they forgot it or suspect someone got into their account.
Linking to articles that help with login and hacking problems can encourage users to explore more options for mitigating their situation.
Connecting your troubleshooting resources with links like that will make it more helpful and add an extra level of guidance for your users.
Get Feedback on the Troubleshooting Guide
The final step in creating your SaaS troubleshooting guide doesn’t involve writing a single word on your part.
This stage is all about getting feedback on your guide to ensure that it’s helpful and efficient at guiding users to the solutions to their issues with the product.
Feedback is essential if you want to be sure that you’ve achieved your goal of creating a valuable resource for your users.
You might think your guide is perfect, but people with different levels of knowledge, backgrounds, and perspectives can notice areas that need improvement.
Therefore, you can ask the people who actually use your guide about its usefulness.
One of the simplest ways to do so is by implementing a one-question satisfaction survey that the users can answer with one click.
Take a look at the example from Charthop below.
The simpler the feedback form is, the greater the chances that the users will provide the feedback you need.
A question like the one above can be answered in a second, and it can provide you with a great starting point for improving your troubleshooting guide.
Even though you can’t tell what part needs improvement from the answer, you can tell if the guide is generally helpful.
If many users answer with a “No”, you’ll know it’s time to do more research on the possible reasons for that.
Your users aren’t the only ones who can provide valuable feedback. The members of your team can also be a great source of information about the quality of your guide.
For example, you can give your guide to the members of your team to test it. If you use a tool like Archbee for writing a guide, they can submit feedback in the documentation itself.
Any team member you give permission to can highlight parts of the text, write comments, mention others, link to documents, etc.
There are many collaboration features that can simplify getting feedback about your guide and implementing that feedback to make the resource as helpful as possible.
Conclusion
If you want to do something right, you should follow the proper procedures.
That’s true for most things in business and life, and writing a troubleshooting guide is no exception.
Luckily, now you have the steps to creating a detailed and helpful troubleshooting guide for your SaaS product.
If you follow the steps from this article, you’ll end up with a resource that will help your customers, as well as your team.
It will be a document you can confidently give to anyone looking for help with issues with your product.
‍
