Troubleshooting instructions should help a customer choose the next action from something they can actually observe. A list such as “refresh, sign out, try another browser” often destroys useful clues while asking everyone to repeat the same attempts. For one symptom, write a short decision tree containing a question, possible answers, a safe action and an outcome that ends the task or leads onwards. You can publish this structure in a knowledge base without building a separate diagnostic tool.
Describe the symptom before guessing the cause
Describe the symptom using observable language, for example “After selecting Export, I cannot see a file”. Avoid a title such as “Exporter failure” unless the underlying cause has been confirmed. The customer might have an unavailable button, insufficient permission or a completed download in an unexpected location, and each situation calls for a different route. Explain which screen and action the guide covers so someone with a similar but distinct problem does not enter the wrong branch.
Take three recent reports of this symptom and write down the exact messages and the action immediately preceding the problem. Remove customer details while retaining interface names needed to follow the instructions. If the cases affect only a particular group, investigate their technical differences separately using the approach to errors affecting some users. The customer article should expose distinctions available on their screen, rather than presenting every hypothesis the team has discussed.
Ask a question whose answer changes the action
A decisive question leads to different actions instead of merely confirming that the problem exists. “Is the export broken?” adds little, whereas “Can you select the Export button?” separates two states the customer can check. Explain how to recognise them: an available button can be selected, while an unavailable one remains disabled when approached. Avoid questions about internal component names or settings the customer cannot access, because uncertainty about those details will be mistaken for evidence.
Keep the answer options at each point manageable so users do not need to compare their entire screen with a catalogue of faults. For “I am not sure”, offer a way to observe the state, such as locating the area that displays a message. Do not silently treat uncertainty as “No”, which routes some people into the wrong branch. Walk through each route yourself and check that the answer really changes the next action rather than merely changing its wording.
Give every branch an action and a visible result
A safe action can be performed without deleting information, disabling security controls or changing settings for the whole organisation. In the illustrative export guide, begin by checking the selected report, the permission message and the browser download list. Do not suggest installing extensions or recreating the report when the available observations do not justify either step. The table describes three branches of one symptom; it does not describe an actual Meetlead report exporter.
Scroll the table sideways to see all columns.
| Observation | Safe action | Where to go next |
|---|---|---|
| The export button is unavailable | Check that the report and range are selected | Recheck the button after selection |
| The button works but a permission message appears | Ask an administrator to check access | Do not repeat the export without an access change |
| A download starts but the file is not visible | Check the browser download list | Find the file or record the exact message |
After each action, state an observable result such as “The button is now available” or “The download list shows the file name”. Replace “If it worked, stop” with the evidence needed to consider the task complete. If the outcome differs, name the next branch precisely instead of telling the customer to restart the whole article. Someone who accidentally switches tabs should be able to return to the last confirmed state without losing track of the reasoning.
Write a complete route rather than a set of labels
An illustrative instruction could say: “Open the report you want to download and check the Export button. If it is unavailable, select the report and the range required on this screen, then check the button again. If it is available, select it once and read the message. A permission message leads to the access check, while a download that starts leads to the browser download list.” Every sentence provides a condition the customer can observe.
The next part might read: “If the download list contains the file, open it and check that it belongs to the selected report. If an error appears instead of the file, record the message and the time of the attempt, then stop repeating the action.” Adapt this fictional example to your own application; it is not a universal remedy for download failures. Evidence from a stopped branch can inform a task description based on a customer error without asking the person to reconstruct everything again.
Google’s guidance on writing procedures recommends establishing the task and context of the steps. This decision tree is our proposed editorial method, rather than a description of automated product diagnostics.
Separate prerequisites from the repair route
A prerequisite checks whether the customer can start the task at all, whereas a troubleshooting branch investigates a problem already observed. A required role or an existing report belongs at the beginning as a condition for starting. Do not send someone without access through downloading, changing browsers and other attempts before finally revealing the restriction. The article on instruction prerequisites explains how to write that opening in a way that offers a useful alternative.
Mark a clear stopping point where the self-service route ends. This may be a setting the customer cannot access, a message requiring administrator intervention or the same error recurring after one justified action. Explain what to retain: the screen name, the message and the outcome of the last action. Do not request passwords, files containing customer information or a screenshot of the entire account when a short description is sufficient to distinguish the branch. The same applies to a rejected gift card: the last characters of the code and the message are enough, as our guide on what to do when a gift card is not working shows.
Test the route with someone who does not know the answer
An editorial walkthrough means following the guide without the author supplying missing steps aloud. Give another person one described state and ask them to choose the next action using only the article. Note where they have to guess a button name, interpret an outcome or work out how to return. If they start asking about the cause, check whether the text has accidentally turned an observation into an explanation that the team has not verified.
Explore Meetlead MeetAI and the knowledge base to check the available options for publishing help and working with articles as a team. Start with one well-described tree, then compare it with the real interface and the reader’s permissions. After an interface change, revisit the branches, particularly those that depend on a message name or button location. The article remains useful only while its distinctions still exist in the product customers are using.
Questions about troubleshooting instructions
How many branches should an article contain? Enough to distinguish the main visible states of one symptom. Start with two or three questions and add variations only when they change the recommended action.
If the tree covers many screens and separate tasks, divide it into articles connected by descriptive links. Readers should understand why they are moving to a different instruction instead of feeling that the first route failed.
Can the guide recommend refreshing the page? Yes, when you know the effect on the current task and first check for unsaved work. Explain what survives and what the customer should preserve beforehand, based on verified application behaviour.
Do not make refresh the default action for every branch. One justified attempt should end with evaluating the result rather than beginning an endless series of retries.
