A vague bug report costs everyone time. The developer asks follow-up questions, you answer a day later, and the real problem stays unfixed. A good screenshot, plus a few lines of context, can cut that loop to zero. Here is how to write a report that gets fixed on the first read.
Start with the one-sentence summary
Write a title that says what broke and where. Compare "It doesn't work" with "Checkout button does nothing after applying a discount code on mobile." The second one tells the developer where to look before they have opened the screenshot.
Describe what you expected and what happened
Every useful report answers three questions:
- What did you do? The exact steps, in order.
- What did you expect? The result you thought you would get.
- What actually happened? The result you got, with the screenshot attached.
Numbered steps are better than a paragraph. If someone can follow them and see the same problem, the bug is reproducible, and a reproducible bug is half fixed.
Capture the right thing
The most common mistake is capturing too little or too much.
- Include the error message in full. Do not crop it off at the edge. Text in error dialogs is often what the developer searches for first.
- Include the address bar for web bugs. The URL tells the developer which page, and sometimes which account or environment.
- Include the surrounding context. A tight crop of one button hides the fact that the page behind it was half-loaded or showed a warning banner.
- Include version information. If the app has an About screen, a screenshot of it (or a typed version number) saves a round of questions.
For a problem that happens over time, such as a flicker, an animation glitch or a multi-step flow, a short screen recording beats a still image. Use a screenshot for a state, and a recording for a sequence.
Annotate instead of describing
A red arrow or box does more than a sentence. Draw attention to the exact element that is wrong, and keep the annotation minimal: one box, one arrow, maybe a short label. Too much markup hides the problem.
Add a short label for the unexpected thing ("Total should be $42, shows $0"). Avoid covering the area you are pointing at, and use a colour that contrasts with the interface.
Protect private information
Before you attach a screenshot to a public issue tracker or a shared channel, check it for:
- Email addresses, names and phone numbers
- API keys, tokens and passwords, including ones in the URL or in a visible console
- Customer data in tables or lists
- Browser tabs and bookmarks that you would rather not share
Blur or black out anything sensitive. A solid fill is safer than a light blur, which can sometimes be reversed.
Add environment details
Many bugs only happen in one setup. Include:
- Operating system and version
- Browser or app version
- Screen size or device, if the bug looks layout-related
- Whether you were logged in, and as what kind of user
- How often it happens: every time, sometimes, or once
One issue per report
If you found three problems, file three reports. Bundled reports get partly fixed and then forgotten, and they are hard to track and close. Link them to each other if they seem related.
A template you can copy
| Field | Example |
|---|---|
| Title | Export button produces an empty CSV when a filter is active |
| Steps | 1. Open Reports. 2. Filter by "This month". 3. Click Export. |
| Expected | CSV with the filtered rows |
| Actual | File downloads but contains only the header row (screenshot attached) |
| Environment | Windows 11, version 2.4.1, Chrome |
| Frequency | Every time with filters, never without |
Name your files
A file named checkout-error-promo-code.png is far easier to find later than Screenshot (47).png. If your tracker supports it, paste the image directly into the description so it appears inline instead of as a download link.
Making this faster. If you file bug reports regularly, a capture tool with a built-in markup editor and one-click copy removes most of the friction. See our guide to Windows screenshot shortcuts for the built-in options, or SnapIt if you want annotation and capture history in one place.