Developers receive a large share of bug reports that are just an image and the words “it’s broken”. The screenshot is doing half the job; the other half comes from how it was captured, annotated, and packaged. This guide is a practical template for making screenshots carry their full weight.

What a good screenshot-based report contains

  1. The state itself: the actual screen showing the problem, not a description of it.
  2. A pointer: an arrow or box identifying the exact element involved.
  3. Context metadata: which app/build, which OS, and ideally the resolution, so the developer can rule out environment-specific rendering.
  4. Repro steps: numbered, short, in order. The screenshot is step N; the reader needs steps 1 through N-1.
  5. Expected vs actual: one line each. “Expected: dropdown stays open. Actual: dropdown closes immediately.”

Everything else is optional. Resist the urge to attach five screenshots when one annotated one plus three repro steps tells the whole story.

Capturing for a bug report specifically

Capture the right scope

  • Region, not full screen, in most cases. A tight crop around the broken component reads faster on mobile and leaves less of your environment exposed.
  • Full screen only when position matters, like a layout bug where the relationship between panels is the point.
  • Capture both states for transition bugs. If clicking X makes Y disappear, you need the before and after. Two small shots beat one ambiguous one.

Annotate with intent

The annotation guide covers the tools in depth; for a report you mostly need:

Annotation When to use it
Arrow One specific element is wrong. The default choice.
Rectangle A region or container misbehaves (spacing, overflow, clipping).
Text label Step numbers in multi-step repros; “expected” vs “actual” callouts.
Blur Anything sensitive that isn’t relevant to the bug. Always.
Crop Remove empty space after annotating so the mark carries the frame.

Two rules of thumb:

  • One arrow per screenshot. If you need three arrows, you probably need three screenshots.
  • Blur before upload. Tokens, customer names, and internal URLs get blurred in the editor before the image leaves your machine. Which cover to use depends on what has to stay readable. There is no un-blur after sharing.

Include the metadata that helps

A share page that shows dimensions, file size, and capture date removes a round-trip of “what resolution were you on?” Shotivo’s share pages display width × height, file size, creation date, and expiration, so pasting the link conveys that context automatically.

In the report body itself, add:

  • App name + version (e.g., “Shotivo 1.x” or the affected product’s build number)
  • OS + version (“macOS 15.2”)
  • One-line environment note if relevant (“external 4K display”, “VPN on”)

The workflow: three seconds to a shareable shot

With a menu bar capture utility (Shotivo’s defaults shown):

  1. ⌘⇧9: drag over the broken region. Editor opens instantly.
  2. Click the arrow tool, mark the element; blur anything sensitive; crop tight.
  3. ⌘↩ (Share): uploads and copies a shotivo.app/s/… link to your clipboard.
  4. Paste the link into the ticket, followed by repro steps.

Total from first keypress to paste-ready link: roughly three to five seconds. Free links expire after 7 days; Pro links can remain live for up to 90 days (90 days by default). Download the original if the ticket needs a durable local copy. How retention works per tier if you’re unsure which limit applies to you.

Template

[App] [Component] · [one-line summary]

Steps:
1. …
2. …
3. Observe: <what happens>

Expected: <what should happen>

Screenshot: <paste share link>
Env: macOS 15.2 · app build 1.x · <display note if relevant>

Fill the template in under a minute and you’ve produced a report a developer can act on without a follow-up call. The screenshot does the showing; the three lines do the telling.

Common mistakes

  • “See attached.” with no repro steps. The developer has to guess the path to the state.
  • Full-screen capture of a tiny problem. The arrow points at 2% of the frame.
  • Unblurred secrets. The report gets forwarded, archived, indexed; your token is now public.
  • Five screenshots of the same state. One good one plus words beats five mediocre ones.
  • Screenshot taken after “fixing” it. Capture the broken state first; you can always re-capture later.

The bar is low and worth meeting: could a developer who has never seen this app reach the broken state from your text alone, and see exactly what’s wrong from your image? If yes, the report is done.