Organise a troubleshooting guide by symptom, because that is all the reader has. They arrive with an error string, a blank screen or a process that hangs, not with a theory about which subsystem is at fault. Every entry should be findable by pasting the exact text they are looking at, and should contain four things: what they are seeing, why it happens, how to confirm it is this and not something similar, and what to do about it.
A guide organised by component instead is a guide that only helps people who already know where the problem is, which is precisely the group who did not need it.
Start from what the reader has in front of them
Somebody opening a troubleshooting page is in a specific state: something failed, they are mildly irritated, and they have a string on their screen. That string is the only reliable index into your guide. Everything in the page structure should serve the act of pasting it into a search box and getting one confident answer.
Error: EACCES: permission denied, open '/var/lib/app/config.yaml'
at Object.openSync (node:fs:601:3)
at readConfig (/opt/app/lib/config.js:44:18)
at start (/opt/app/lib/server.js:12:22)The literal error text belongs in the page, verbatim, including the parts that look like noise. Readers paste whole lines. If your guide paraphrases the message as “a permissions error”, the paste finds nothing and they go to a forum instead.
Headings are weighted by search engines and by your own site search, and they generate anchors. A heading containing the literal error message is the single most effective thing you can do to make a troubleshooting entry findable. See Documentation Search for why the index has to cover code blocks too.
Organise by symptom, not by cause
| Organised by… | What the reader needs to know first | Works when |
|---|---|---|
| Symptom | What they are seeing. Nothing else. | Almost always. This is the default. |
| Subsystem | Which component failed. | Your readers are operators who already read the logs. |
| Task | What they were trying to do. | Failures cluster tightly around a few workflows: installation, first deploy. |
| Error code | The code, exactly. | You have stable, documented codes. Then the code is the symptom. |
The commonest mistake is a guide organised the way the engineering team thinks about the product. That organisation is real and useful, for the engineering team. Readers are on the outside, and from outside, a database connection error and an expired credential look identical: the page did not load.
The anatomy of one entry
Every entry, no exceptions, in this order.
-
The symptom, in the reader’s words. The literal error, or a precise description of the observable behaviour. “The build hangs at 40% and never completes”, not “build performance issues”.
-
The cause, in one or two sentences. Not a design document, just enough for the reader to recognise their situation and to trust the fix.
-
How to confirm it. A command to run, a log line to look for, a setting to check. This step is what stops a reader applying the wrong fix to a similar-looking problem, and it is the step most often skipped.
-
The fix. Numbered, complete, with the commands in full. If there are several fixes depending on environment, split them into labelled branches rather than a paragraph of conditionals.
-
How to prevent it. A config change, a lint rule, a check in CI. Optional, but this is the part that reduces the ticket count rather than just closing tickets.
-
What to do if that did not work. Always present. The next thing to try, or how to get help and what to include when asking.
An entry whose fix does not work leaves the reader worse off than when they arrived: they have now spent ten minutes and still have the problem. A single closing line pointing at the support channel, with a list of what to attach, converts a dead end into a good ticket.
Use collapsed sections for the long tail
Troubleshooting guides grow. Twenty entries on one page is a wall of text; twenty collapsed entries is a scannable index that still matches an in-page search, still holds its anchors, and still prints. Keep every entry on one page for as long as you can: a reader who does not know which of your six troubleshooting pages to open has a worse problem than a long page.
Permission denied when reading a config file
The service account cannot read the file. Confirm with ls -l on the path in the error and compare the owner against the user in your service definition.
Fix: change ownership to the service user rather than loosening the mode. A world-readable config file containing credentials trades one incident for a worse one.
Requests fail with 429 after a deploy
Your instances restarted together and are now retrying in lockstep. The rate limiter sees one large burst rather than steady traffic.
Fix: add jitter to the retry backoff and stagger instance start-up. Confirm it is this rather than a genuine quota change by checking whether the 429s stop within a few minutes without intervention.
The page loads but the styles are missing
Almost always a cached asset with an unchanged version string. Confirm by fetching the stylesheet URL directly and comparing it against the file on disk: the served bytes will be current while the rendered page is not.
Fix: hard reload to verify, then correct the versioning so ordinary readers do not have to.
The process starts, then exits with no output
Usually a failure before logging is configured. Confirm by running the same command in the foreground with the log level raised.
Fix: whatever the newly visible error says. The lesson for the product is that configuration errors should be reported before the logger is initialised, not after.
Feed the guide from support, not from imagination
The entries worth writing are the ones people are already asking about. Everything else is speculation, and speculative troubleshooting entries are expensive: they take up space, they rank in search, and they are rarely accurate because nobody ever hit the problem.
- Read last month’s tickets. Group them by symptom. Anything appearing three times is an entry.
- Read the zero-result search queries on your own docs site. Error strings that return nothing are entries waiting to be written.
- Close the loop. When support answers a question that should have been in the guide, the guide entry is part of closing the ticket, not a follow-up task that never happens.
- Delete entries for fixed bugs. An entry describing a problem that no longer exists in supported versions sends readers down a path that cannot help them. Note the version it applied to and remove it once that version is out of support.
A troubleshooting guide is a record of the questions you are still getting. If it is not changing, either your product stopped changing or nobody is reading your tickets.
A short checklist
- Every entry is findable by pasting the literal error text.
- Symptom first, cause second, confirmation third, fix fourth.
- Commands are complete and copyable, not fragments.
- Every entry says what to do if the fix does not work.
- Entries name the versions they apply to.
- The guide is reviewed against last month’s tickets, not against a plan.
Doku’s accordion block is built on native <details>, so collapsed entries stay keyboard-accessible, print expanded and remain findable by in-page search. See the Troubleshooting page for a worked example.