Troubleshooting Guide Template
Lay out the questions, fixes and escalations as a decision tree, and keep how to run each check and what to record one click behind it.
Free forever on the Personal plan
Troubleshooting guides: an example
One question at a time
Each diamond asks one thing, and each answer leads somewhere.
The fix under each check
Green boxes are fixes and red boxes are escalations, so the colour says what to do.
Evidence for the next team
Each check lists what to record, so escalations arrive with the facts.
The basics
What is a troubleshooting guide?
A troubleshooting guide helps someone find and fix the cause of a known symptom, such as a till that cannot take cards: it asks questions in order, gives the fix for each likely cause, and says when to escalate and with what evidence. It is usually written as a decision tree.
Guides written as long lists of possible causes leave the reader to decide what to check first. A decision tree asks the most useful question first and narrows the problem with every answer, so first-line staff fix more and escalate better.
In Blueprintr each check, fix and escalation is a box on the tree with a stratum behind it: how to run the check, what to record, the steps of the fix and who to escalate to.
Why Blueprintr
Guides first-line staff can follow
The decision tree on the canvas, the how-to behind every box.
Decision trees that read
Draw checks as diamonds with labelled yes and no paths, fixes in green under the check they answer and escalations in red at the end of each row.
VellumHow to run each check
Give every check a stratum with the steps, the screens to look at and the evidence to record, and every fix its numbered procedure.
StratumLinked from where people start
Link the guide from knowledge base articles and procedures, so a reader who hits the symptom lands on the first question.
Updated after each incident
Add a dated update block whenever an incident changes the guide, so readers see what changed and why.
Monitor snapshots on Enterprise
Continuum Link attaches dated snapshots from tools such as Pingdom, Checkly or Datadog to the check that asks whether a service is up.
ContinuumEmbedded in the service desk
Publish the guide and embed it in the service desk portal or wiki; readers open each check without leaving the page.
Blueprints
How to
How to write a troubleshooting guide in Blueprintr
Create a blueprint
Sign up free and create a blueprint named after the symptom.
Ask the first question
Start with the symptom and the question that splits the problem in two.
Add the checks and fixes
Add each check in the order to try it, with its fix directly beneath it.
End each path
Finish every path with a fix that works or an escalation to a named team.
Add the detail
Add a stratum to each box with how to run it and what to record, then publish.
FAQ
Questions about troubleshooting guides
Is this troubleshooting guide template free?
Yes. The Vellum editor, decision tree shapes, strata and embeds are on the free Personal plan. Monitor snapshots with Continuum Link are part of Enterprise.
What should a troubleshooting guide include?
The symptom as people report it, a first question that splits the problem, checks in order with a fix under each, when to escalate and to whom, the evidence to record, and an owner and review date.
How do I write a good decision tree?
Ask the question that rules out the most first, keep one check per box, label every path, put each fix directly under its check, and end every path with a fix or an escalation.
What is the difference between a troubleshooting guide and a runbook?
A troubleshooting guide finds the cause of a symptom, often for first-line staff. A runbook is the procedure for handling a known event or alert, usually for whoever is on call.
Can I link the guide from our knowledge base?
Yes. Every published blueprint has a link, and public or unlisted guides can be embedded in a wiki or portal, where readers can open each check in place.
How do I keep a troubleshooting guide current?
Review it after every incident it should have helped with, add a dated note of what changed, and publish. Every publish keeps a snapshot of the guide.