Skip to content
Documentation

Troubleshooting Guide Template

FieldValue
TypeSkill Resource
Source~/.copilot/skills/technical-writing/references/templates/troubleshooting.md
DescriptionNot specified

Source Content

Troubleshooting Guide Template

Symptom-first help for a reader who is already stuck and skimming fast. Diátaxis mode: how-to, organized by what the reader sees, not by system internals.

Skeleton

# Troubleshooting {{system or feature}}


{{Incident scene, 2–3 sentences: "Jack chased the database for an hour;
Jill checked the cert expiry first. This guide starts where Jill
started." Then one sentence: what this covers and where to go if the
symptom isn't here.}}


{{Mermaid flowchart: the triage decision tree from symptom to section —
follow the diagram rules in ../mermaid.md.}}
_{{What to notice: start from what you see, not from what you suspect.}}_


## {{Exact error message or symptom, verbatim}}


**What it means:** {{one sentence.}}


**Fix:**


1. {{Step with expected result.}}
2. {{Step with expected result.}}


**If that didn't work:** {{escalation or the deeper diagnostic.}}


## {{Next symptom, same shape}}


{{Repeat the pattern — one section per symptom.}}


## Still stuck


{{Where to ask, what to include: versions, logs, the command that failed.}}


{{The useful ending, one line: what Jill knew that Jack, who chased the wrong lead, didn’t.}}

Rules for this template

  • Headings use the reader’s words. Use the exact error text they will paste into search, not internal component names.
  • Each symptom section stands alone. Assume the reader landed on it straight from search — every page is page one.
  • Log fields and config values go one per line, never chained in a sentence.
  • The opening incident scene is 2–3 sentences, never a novel — it sets the tone before the triage tree.
  • The useful ending is one line, folded into “Still stuck” — never its own heading.
  • Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
  • Reminders: story, own line per person · useful ending.
  • Format: short paragraphs · lists and tables · diagram + “what to notice”.