Troubleshooting guides

Usually software is considered only to be code that is executable, sometimes the documentation is also considered part of software, but are the troubleshooting guides part of software? Are these rulebooks useful for the team that uses, maintains, develop or support the software?

What is a troubleshooting guide?

A troubleshooting guide is a rulebook or more explained a collection of items that should help the users navigate through the issues that could happen.

In my case, I work as a platform engineer and the troubleshooting guides that I help maintain are directed to developers whose software runs on the platform.

Why would your application need one?

Applications need operational tasks, they fall in inconsisten states, or need some manual labor to have their state restored. Of course, I mean software that runs in servers, but this could also be applied to desktop applications or even mobila applications.

Of course, you could think it is silly to expect end-users to follow a guide to customize a desktop application but some times (dependending on the use case) and the domain we are talking about, it could make sense.

Applications for highly-specialized specialists could be not as polished as we would like and the users could be act as tech-savy users / part-time IT support workers.

Why would your team interested in one?

If you provide support in some way or another to an application, having a guide that you can follow and not having to think about the issue is a must. Human brains are limited and the capacity to remember things should not be taken for granted.

How could you create and update a troubleshooting guide?

Do not do anything, just wait until the issues happen. Then, gather all information about an issue, and once it is resolved, I include all the steps that have led to a solution.

And after that… What?

Check how many users are checking each item of the guide and sum the expected time for the issues that have not been arised. How many hours of work in your team have been saved?

Also take in account the issues and try to automatize the process. Is it possible? If it was, you would achieve not only the removal or support tasks, but the reduction of operational tasks by the developers.

Conclusion

Now it is your turn to think: do you have a troubleshooting guide at your work? How do you keep it up-to-date?