All posts

How to Write Effective Bug Reports with Annotated Screenshots

5 min read

The most common complaint developers have about bug reports isn’t that there are too many — it’s that they don’t contain enough information. “The button doesn’t work” is a sentence, not a bug report. And even well-intentioned reports often leave out the one detail that would make the bug reproducible.

Annotated screenshots bridge this gap. They show the exact state of the UI, highlight the specific element that’s broken, and provide visual context that words alone can’t match.

Why most bug reports fail

A typical bug report contains a title, a description, and maybe some steps. But without visual evidence, several things go wrong:

  • Ambiguity.“The dropdown is broken” — which dropdown? On which page? In which state?
  • Missing environment details. The bug might only appear at a specific viewport width, with certain data, or in a particular browser. A screenshot captures all of this implicitly.
  • Back-and-forth. Without a screenshot, the developer has to ask clarifying questions, the reporter has to answer, and days pass before anyone looks at the actual code.

Anatomy of a good bug report

Every effective bug report answers five questions:

  1. What happened? The observed behavior.
  2. What should have happened? The expected behavior.
  3. How do you reproduce it? Step-by-step instructions.
  4. What’s the environment? Browser, OS, viewport, user role, data state.
  5. What does it look like? Visual evidence.

The fifth question is where screenshots come in — and annotations are what make them useful rather than just decorative.

How annotations turn screenshots into evidence

An unannotated screenshot is a photo of a crime scene with no yellow tape. The viewer knows something happened but doesn’t know where to look. Annotations fix this by:

  • Directing attention. An arrow pointing at the broken element saves the developer from scanning the entire page.
  • Adding sequence.Numbered callouts (“1. Click here → 2. This field shows wrong value”) turn a static image into a walkthrough.
  • Highlighting absence. A circle around an empty space where a button should be is clearer than describing the missing element in text.
  • Capturing transient states. Tooltips, error messages, and loading states that disappear can be captured and annotated before they vanish.

Annotation tips

Use arrows and boxes, not freehand circles

Clean geometric annotations look intentional and are easier to follow. Freehand scribbles can look sloppy and make it unclear exactly what’s being highlighted.

Pick one highlight color and stick with it

Red is the convention for a reason — it stands out against most UI backgrounds. If you need a second color for a different type of callout (e.g., “expected” vs. “actual”), use green. More than two colors creates visual noise.

Add short text labels

An arrow is good. An arrow with the label “wrong total” is better. Keep labels short — three to five words — so they don’t clutter the image.

Show before and after when possible

If the bug involves a state change, capture both states: the correct behavior and the broken behavior. Place them side by side or in sequence so the contrast is obvious.

Crop thoughtfully

Too tight and you lose context. Too wide and the bug gets lost. Include enough surrounding UI to orient the viewer (the page header, the form section) but not the entire browser window.

From screenshots to report

For simple bugs, a single annotated screenshot pasted into a Jira ticket is enough. But for complex issues — multi-step reproduction, cross-browser comparisons, or regression testing — combining multiple screenshots into a single PDF report makes the bug report self-contained and easy to reference.

Tools like Trace are built for exactly this workflow: capture screenshots in the browser, annotate them in place, arrange them in order, and export the whole sequence as a numbered PDF. The report becomes a single attachment that tells the complete story of the bug.

Whatever your tooling, the principle holds: a bug report with annotated screenshots gets resolved faster because it removes ambiguity. The developer sees exactly what you see — and that’s half the battle.