How to annotate screenshots for bug reports
What a screenshot in a ticket has to show, why the tight crop so often removes the one thing the engineer needed, how to number reproduction steps, and what to redact before it goes into a tracker that keeps things forever.
A screenshot in a bug report is doing a different job from a screenshot in a chat. It is evidence, it will be read by someone who was not there, and it will be read weeks later by a third person trying to work out whether a new report is the same bug. That changes what belongs in it, and it changes it in a direction most people find counterintuitive: a bug screenshot should usually be larger and less cropped than feels natural.
The reason is that the reporter crops to what they think the bug is, and the engineer needs what the reporter did not think was relevant. Which build, which window size, which account, which state, what time. Nine times out of ten the follow-up question is answerable from a screenshot that was cropped away.
What a good bug screenshot shows
- The whole window, not the failing control. The window title, the URL, the tab, the sidebar and the visible state around the problem are all evidence.
- The error text, in full, readable. If it is truncated in the interface, expand it or paste it as text alongside — an engineer will search for that string, and a search cannot be run against a picture.
- The state that produced it: what was selected, what was typed, which filter was applied, whether the list was empty.
- The version. Build number, app version, browser and operating-system version. If your app has an About or diagnostics screen, a second screenshot of it is worth more than any annotation on the first.
- The time, which is what lets someone find the matching server log. A visible clock in the status bar is the easiest way to carry it, which is one good reason not to crop the status bar off.
- Whether it reproduces. One screenshot is an anecdote; two of the same failure at different times is a bug.
For anything involving timing, order or a transient state, a screen recording beats a screenshot outright and takes no longer to make. A screenshot cannot show that the spinner ran for eleven seconds before the error, and that is frequently the entire finding.
The crop that loses the evidence
The most common defect in a bug screenshot is a tight crop around the error dialog. It looks focused and professional. It has removed the URL, the account, the window size, the state of the page behind it and the clock, and it will generate a round trip of questions that costs a day.
Do the opposite: capture wide, then annotate to direct attention. A rectangle around the error and an arrow at the control you pressed give the reader the focus that the crop was trying to provide, while keeping everything a second reader might need. Crop only to remove things that are genuinely irrelevant or genuinely must not be there.
The exception is a second, tighter image. Two screenshots — the whole window, and a tight crop of the failing region — cost nothing and answer both audiences. If you attach only one, attach the wide one.
Numbering the reproduction steps
When the reproduction happens on a single screen, numbered markers on one screenshot are the clearest form there is: 1 on the field, 2 on the toggle, 3 on the button, with the written steps underneath matching the numbers. It removes the ambiguity that plain prose carries — "click the save button" is not a unique instruction on a page with two of them.
Three rules that keep this from going wrong. Place the markers beside their targets, not on top, so the reader can still recognise the control on their own screen. Keep the numbers on the image matched to the numbers in the written steps, which means the numbers must renumber themselves when you delete one, or you must place them last. And when the steps span more than one screen, use one screenshot per step; there is no way to show a step on screen B in a screenshot of screen A, and an arrow pointing off the edge of the image helps nobody.
Redact before it enters the tracker
A ticket is not a message. It is stored indefinitely, it is readable by everyone with access to the project — often far more people than the engineer you are talking to — it is exported when the tool is migrated, it is indexed by internal search, and in an open-source project it may be public and mirrored. A screenshot pasted into it is effectively permanent, and deleting the comment later frequently leaves the attachment reachable by direct link.
So run the check before the paste, not after.
- Customer data: names, emails, phone numbers, addresses, order contents. Replace with test data and re-take the screenshot where you can — a screenshot of a test account is better than a redacted screenshot of a real one, and it is better precisely because there is nothing to redact.
- Credentials and tokens: anything in the URL, an API key in a config panel, a session identifier in a developer console, a QR code on the screen. Cover the whole QR code, not part of it.
- Internal identifiers you would rather not have in a public repository: server hostnames, internal domains, employee names in a comment thread.
- The surroundings: browser tabs, the notification banner, the desktop behind the window, the sidebar of another product.
- Then export a flat file, open that file, and look at it before you attach it. A cover that is still an editable object hides nothing.
The tension with the previous section is real and worth naming: you were told to capture wide and are now being told the wide capture contains more to redact. That is the trade. Resolve it by capturing wide from a test account where possible, and by redacting rather than cropping when it is not — cover the customer’s name and keep the URL, the version and the clock.
Doing it in Marka
The loop this page describes is short in Marka and shorter still on the Mac, where a screenshot goes to the clipboard with Control-Shift-Command-4, pastes straight in, and comes back out to the clipboard for the ticket without a file ever existing. Every tool has a single letter on the Mac — m for the redaction brush, a for arrow, r for rectangle, n for numbered markers — so covering the customer’s name and boxing the error is a few keystrokes rather than several toolbar trips. The numbered markers renumber themselves when you delete one, by creation order rather than by which marker is on top, so the image never ends up reading 1, 3, 4 against a list that says 1, 2, 3.
Redaction is a brush in three modes; mosaic is free, and blur and a solid block are part of the one-time Pro purchase, as are the annotation tools. For a ticket, prefer the solid block: a bug report is exactly the context where a redaction has to survive being looked at by people you did not anticipate. On Mac there is also an on-device scan that proposes phone numbers, emails, card-like numbers, faces and URLs to cover, each with a checkbox — useful as a final pass over a wide capture, though it proposes rather than acts and it will miss things, and it does not exist on iPhone or iPad. Nothing is uploaded, which matters more than usual when the screenshot is of an internal system. It is a scratch pad and keeps no copy after you close it, so attach or export before you close the window. The interface is in Simplified Chinese in this version — worth knowing before installing.
Frequently asked questions
How much of the screen should a bug screenshot show?
More than feels natural. Capture the whole window, including the title bar, the URL or tab, and the status bar with the clock. The engineer usually needs what you did not think was relevant — the build, the account, the window size, the time — and all of it is free if you capture wide and use an arrow to direct attention instead of a crop.
Should I attach a screenshot or a screen recording?
A recording whenever timing, order or a transient state is part of the problem — a spinner, a flash of the wrong content, a race. A screenshot cannot show that something took eleven seconds, and that is often the finding. For a static wrong value or a visible error, a screenshot is faster to read and easier to search.
Do I need to redact a screenshot in an internal tracker?
Yes, for customer data. A ticket is readable by everyone with project access, kept indefinitely, exported on migration and indexed by internal search, and deleting the comment often leaves the attachment reachable by direct link. Better still, reproduce on a test account so there is nothing to redact.
Should I include the error message as text as well as an image?
Always. Engineers search for error strings, and a search cannot be run against a picture. Paste the full text — not truncated — alongside the screenshot. The image proves the context; the text is what someone finds when the same bug is reported again in four months.
What is the fastest way to do this on a Mac?
Control-Shift-Command-4 to put a region on the clipboard without creating a file, paste into a markup app, cover anything that should not be in a tracker, draw one rectangle around the error and number the steps if there are several, copy the result out, and paste it into the ticket. No file is written, so nothing is left behind to clean up.
Do it in Marka
Marka is a screenshot markup app for iPhone, iPad and Mac. Brush a mosaic over what should not be seen, point an arrow at what should, number the steps, crop it to the shape you are posting in, and send. Everything is processed on the device — no upload, no account, no analytics, and a 2.4 MB download. Opening, cropping, the mosaic brush and export are free; Pro is a one-time purchase that covers all three platforms.