Learn to write effective troubleshooting guides: symptom-cause-resolution structure, 'If X then Y' patterns, prerequisites, escalation paths, and common mistakes sections.
0 / 10 completed
1 / 10
What is the 'symptom-cause-resolution' structure in troubleshooting guide writing and why is it more effective than a purely procedural format?
Readers of troubleshooting docs are in a problem state — they have a symptom. Structuring by symptom: 'Error: Connection refused on port 5432' → cause: PostgreSQL service not running → resolution: systemctl start postgresql. Structuring by cause alone ('PostgreSQL service management') forces readers to diagnose before they can navigate. Symptom-first lets users Ctrl+F their exact error message and land at the fix. Each symptom should be written as the user would describe it, including exact error message text.
2 / 10
What makes the 'If you see X, do Y' pattern effective in troubleshooting documentation?
'If you see X, do Y' examples: 'If the error includes ECONNREFUSED, the service is not running. Start it with: sudo systemctl start myapp.' vs. 'If the error includes ETIMEDOUT, the service is running but unreachable — check firewall rules.' This pattern lets readers skip irrelevant branches. Avoid: 'Check if the service is running.' Better: 'Run: systemctl status myapp. If it shows inactive (dead), proceed to Step 3. If it shows active (running), skip to Step 5.'
3 / 10
What should a 'Prerequisites' section in a troubleshooting guide contain?
Prerequisites to document: (1) Access required: 'You need SSH access to the affected server and sudo privileges.' (2) Tools required: 'Ensure kubectl, jq, and curl are installed.' (3) Information to gather first: 'Collect the request ID from the error message and the approximate time the issue occurred.' (4) Environment context: 'These steps apply to Linux/systemd environments. For macOS, see the macOS troubleshooting guide.' Missing prerequisites is the most common reason a troubleshooting guide fails — readers get blocked by an undocumented dependency.
4 / 10
How should escalation paths be documented in a troubleshooting guide?
Escalation section template: 'If you have completed all steps above and the issue persists, escalate to the Platform Engineering team. Include in your escalation: (1) The exact error message. (2) Steps you have already tried. (3) Output of: kubectl describe pod [pod-name]. (4) The time the issue started. Contact via: Slack #platform-incidents for P1/P2, Jira ticket for P3/P4. Response SLA: P1 15 min, P2 1 hour, P3 next business day.' Clear escalation paths prevent both under-escalation (struggling too long) and over-escalation (paging on-call for config issues).
5 / 10
What is the purpose of a 'Common mistakes' or 'Pitfalls' section in a troubleshooting guide?
Common mistakes section adds institutional knowledge: 'Common mistake: Running the database migration before stopping the application servers. This causes constraint violations. Always stop app servers first (Step 2) before running migrations (Step 4).' Or: 'Do not restart the auth service while a migration is running — it will invalidate all active sessions.' These warnings come from real incidents and support tickets. Phrase them without blame: not 'users often forget to' but 'A common mistake is to...' or 'Note: Do not...' They turn one engineer's painful experience into a guardrail for all future readers.
6 / 10
Sarah, a junior developer, posted this comment on a code review for the PaymentService:
"The API is returning 500 errors when processing refunds. I checked the logs and saw 'NullPointerException' in the `RefundProcessor'. I tried restarting the service, but it's still failing."
This example demonstrates a classic symptom-cause-resolution pattern. Sarah correctly identified the symptom (500 errors), a potential cause (NullPointerException), and an initial resolution attempt (restart). The incorrect options either oversimplify or miss key elements of this structure – restarting doesn't address the underlying problem, while simply stating 'Insufficient' provides no guidance.
7 / 10
Mark is drafting a troubleshooting guide for the InventoryManager. He wants to use the 'If you see X, do Y' pattern. Which of the following best illustrates this approach?
'If you see an 'Out of Stock' status in the InventoryManager UI, double-check that the product has been removed from any pending orders.'
The 'If you see X, do Y' pattern is highly effective because it directly links a symptom to a specific action. This helps users quickly understand what to check and how to resolve the problem. The other options misinterpret the purpose of this pattern or apply it incorrectly – prerequisites describe system needs, not troubleshooting steps.
8 / 10
David is creating a troubleshooting guide for the UserAuthenticationService. Which of the following should be included in the 'Prerequisites' section?
A) A list of all possible error codes.
B) The hardware specifications of the server running the service.
C) Information about user account types and their associated permissions.
D) A detailed explanation of the authentication algorithm.
The 'Prerequisites' section should provide context that helps users understand *why* an issue might be occurring. Knowing user account types and permissions is crucial for diagnosing authentication problems – it allows you to determine which accounts are affected and why they might not be able to authenticate.
9 / 10
Emily is writing a troubleshooting guide for the DataPipeline. She wants to document escalation paths. Which of the following is the *most* appropriate way to do this?
A) 'If you can't resolve the issue within 30 minutes, contact your team lead.'
B) 'Escalate to Tier 2 support if you encounter errors related to data transformation or schema validation.'
C) 'Immediately notify the entire development team about any downtime.'
D) 'Document all known issues in a shared spreadsheet and update it regularly,'
A clear escalation path specifies *who* to contact and *what information* to provide – this dramatically reduces response time. Option B defines the scope of escalation based on technical issues, while options C and D are inappropriate for handling critical troubleshooting situations.
10 / 10
John is finalizing a troubleshooting guide for the ReportingService. He wants to include a 'Common Mistakes' section. Which of the following would be most relevant?
A) A list of all possible API endpoints.
B) Best practices for writing SQL queries.
C) Frequent errors users make when configuring data sources (e.g., incorrect connection strings, missing permissions).
D) Detailed performance benchmarks for generating reports.
The 'Common Mistakes' section focuses on preventing recurring problems. Identifying common configuration errors (incorrect connection strings, missing permissions) allows users to avoid these issues and reduces the need for support intervention. This aligns perfectly with the symptom-cause-resolution principle.
What will I practise in "Troubleshooting Guide Writing — Symptom-Cause-Resolution Patterns"?
Learn to write effective troubleshooting guides: symptom-cause-resolution structure, 'If X then Y' patterns, prerequisites, escalation paths, and common mistakes sections.
How many exercises are in this module?
This module has 10 multiple-choice exercises, each with instant feedback and a full explanation of the correct answer.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account, sign-up, or paywall.
Do I need to create an account to do these exercises?
No account is required. Just click an option to answer — your score for this session is tracked automatically in the progress bar above.
What happens if I choose the wrong answer?
You'll immediately see which answer was correct, plus a full explanation covering the vocabulary and reasoning behind it — mistakes are where most of the learning happens.
Can I retry the exercises if I want a higher score?
Yes — use the "Try again" button on the results screen to reset and go through all the questions again.
Is my progress saved if I close the page?
No. Progress is tracked only for your current visit; reloading or leaving the page resets the counter. This keeps the exercise simple and account-free.
Where can I find more Knowledge Base Writing exercises?
Browse the full Knowledge Base Writing hub for related drills, or check the "Next up" link below to continue with a connected topic.
How is this different from reading an article on the same topic?
Articles explain vocabulary and concepts in prose; this exercise tests and reinforces that vocabulary through active recall with immediate feedback — the two work best together.
Who writes these exercises?
Every exercise is written by the CoderSlingo team, drawing on real workplace English used in IT roles, then reviewed for accuracy and clarity.