Estimated Read Time: 2 min
Writing Great Technical Issue Reports
Giving excellent detail lets engineers fix your issue faster, without coming back to ask you for more. The more clearly you describe what happened, the sooner it's solved.
Before a fix, engineers reproduce the problem: they try to follow your exact steps on their own machines to make the bug happen again. Once they can see it, they can find the cause and confirm the fix. If they can't recreate it, it's hard to identify what is going wrong. So the closer your report gets them to recreating it, the faster you get a fix.
Do
- Include a screenshot or screen recording
- Note the time it happened
- Copy the exact error message (full text, don't paraphrase)
- Say who is affected (username/email)
- Say what device (laptop/phone, Windows/Mac/iPhone/Android)
- Say which app or website, and the page/URL
- Say what you did, step by step, right before it broke
- Say what you expected vs what happened
- Say if it happens every time or just once
Don't
- Don't wait. Report it immediately; it could be affecting other people too
- Don't wait for it to happen a second or third time before reporting
- Don't just say "it's broken" or "can't log in"
- Don't omit the error message. It's often the most useful clue
- Don't paraphrase errors. Copy the exact text or screenshot
- Don't assume the engineer already has context. If you haven't told them, they don't know it
Frequently Asked Questions
Why do engineers need so much detail to fix an issue?
Before fixing a problem, engineers reproduce it by recreating your exact steps on their own machines. The more detail you provide, such as device, app, error message, and steps, the more likely they can recreate the issue, find the cause, and confirm the fix without coming back to ask for more.
What is the single most useful thing to include in a report?
The exact error message, copied in full or captured in a screenshot. Error messages are often the most direct clue to the cause, so paraphrasing them or leaving them out makes the problem much harder to track down.
Should I wait to see if an issue happens again before reporting it?
No. Report it immediately, even if it only happened once. Waiting for a second or third occurrence delays the fix and the issue may be affecting other people too.