Write a troubleshooting guide around observations the reader can check. Give each step an expected result and an explicit route for both outcomes.

Start with the symptom, then narrow the possibilities. A guide that begins with an assumed cause can send the reader through irrelevant actions.

An illustrative missing-file diagnostic starts with the expected filename, correct package and extraction state before branching.

Start with what the reader can observe. Original instructional illustration; fictional examples are not software screenshots or measured product results.

Define the starting symptom

For an illustrative case, the reader cannot find a required file in a delivered package. State the exact expected filename and the package version before asking them to change anything.

Keep the example's scope clear. It is a guide-writing exercise, not a claim about a particular product's error or file-handling behavior.

Make each check observable

Check

If yes

If no

Is this the issued package?

Inspect extraction state

Find the intended package version

Has it been fully extracted?

Compare the folder contents

Extract it using the documented workflow

Is the expected file present?

Open that copy

Compare with the supplied contents list

Avoid a vague check such as “Make sure everything is correct.” Name what the reader should inspect and what counts as the result.

Each troubleshooting step defines a check, expected result, pass route, fail route and escalation evidence.

Every branch needs a next action. Original instructional illustration; fictional examples are not software screenshots or measured product results.

Keep one meaningful action in each step

If a step contains several actions, the reader may not know which one changed the outcome. Separate checks when their results lead to different branches.

Use a heading or step ID for each destination. “Go to the file-access check” is easier to follow than “try something else.”

Define the stop and escalation points

When the issue remains unresolved, ask the reader to record the symptom, file version and checks already completed. Give the actual support route or responsible role.

Do not make them repeat a long loop indefinitely. Include the point at which new evidence or the source owner's help is needed.

Walk through every branch

  1. Follow a case that passes the first check.

  2. Follow one that fails it.

  3. Confirm every branch reaches an action or named stopping point.

  4. Ask a new reader to explain the checks.

  5. Revise ambiguous wording before issuing the guide.

Ulet provides local DOCX and Markdown editing on Windows and macOS with free basic tools. Keep the guide's decision path and test notes together, and record a successful walkthrough only after it actually happens.