By ScoutMyTool Editorial Team · Last updated: 2026-05-27
Introduction
I have filed enough bugs to know that the difference between a bug fixed today and a bug sitting in the queue is usually how easy the report is to read. The format that has worked across product, design, and engineering teams: a single PDF with steps and screenshots in the right order, sane annotations, and three lines of metadata at the top. This is the exact recipe I follow, with the small details that make engineers grateful instead of annoyed.
Vocabulary, quickly
| Term | Meaning |
|---|---|
| Repro steps | Numbered actions that reproduce the bug from a fresh state |
| Expected vs actual | The two outcomes — the report's thesis |
| Environment | OS, browser, app version, account state, network |
| Annotation | Arrows, circles, callouts added to screenshots |
| Flatten | Bake annotations into the page so they cannot be edited |
| Severity tag | P0/P1/P2 or sev-1/2/3 — helps triage |
| Attachment metadata | Filename, size, MIME — kept inside the PDF or as appendix |
Step by step
- Capture screenshots in order during reproduction. Name them 01-, 02-, 03- so the merge order is automatic. Resist re-shooting; the natural sequence carries the story.
- Annotate each screenshot. One arrow + one short label per shot. More annotations = more confusion. The arrow points at the surprising thing, the label says what was expected.
- Merge screenshots into one PDF. In numeric order. PDF preserves the layout regardless of who opens it.
- Write the repro steps as a one-pager. Step 1 leads to screenshot 01, step 2 to screenshot 02. Export to PDF.
- Add an environment + metadata page. OS, browser, app version, account tier, date/time, network. PDF makes this a fixed reference for the engineer.
- Merge: steps → environment → screenshots. One PDF, three sections. Engineer opens once and has everything.
- Flatten annotations. After review, flatten so the report cannot be edited downstream — what you sent is what they see.
- Name the file with the bug ID. bug-1234-checkout-error.pdf. Predictable filenames make ticket linking effortless.
Practical checklist before you send
- Name screenshot files with a leading two-digit number (01-, 02-, 03-) so the merge order is automatic and the engineer scrolls through the reproduction in the correct sequence.
- Limit one arrow and one short label per annotation — multi-arrow callouts confuse the reader and dilute the surprising thing the shot was meant to show.
- Reproduce the bug from a fresh state once before writing the report; "works on my machine for me but not in your steps" is usually a hidden state assumption you forgot to write down.
- Include the exact version strings (OS, browser, app), not "latest" — versions drift and a bug filed against "latest Chrome" is harder to triage in three months than one filed against "Chrome 130.0.6723.69".
- Flatten the final PDF before sending so annotations and any redaction marks bake in and cannot be edited downstream.
- Compress to under 5 MB so attachment limits do not strip it; engineers triage faster when the file opens in one click.
- Re-read your own bug report at the top of your next session before assigning blame; if past-you cannot follow it, the engineer cannot either.
Related reading and tools
FAQ
- Why one PDF instead of a folder of screenshots and a doc?
- Engineers open a single PDF; they don't open a folder. The friction of "step 2 is in slide deck, screenshot 3 is in attachments tab" loses you a day of triage time. A single PDF with steps next to the screenshots they produced gets read end-to-end and gets a fix or a question back the same day.
- How many screenshots should a bug report have?
- As many as it takes to show the repro path, no more. For a one-click bug, two shots (before and after). For a multi-step flow, one per state change. If you have 20 screenshots, the bug is probably actually three bugs — split it.
- What goes on the environment page?
- OS + version, browser + version, app or service version, account tier, locale, network conditions if relevant (VPN, throttled, offline). Date and time of the reproduction. Reproducible-from-zero credentials if it requires a specific account state. One page is enough; bullet list, no prose.
- Should I include logs in the bug-report PDF?
- Yes — as an appendix, in fixed-width font, on its own page so the engineer can scroll directly to it. If the log is more than two pages, attach it separately and reference the filename in the PDF. Logs in the PDF make the report self-contained; the engineer does not have to chase a Slack thread for a stack trace.
- How do I capture a video bug in a PDF?
- Embed key frames as screenshots in the PDF and link to the full video file (drive, S3 link). PDF is not a great video container, but it is a great index of stills with timestamps that points the engineer at the right second of the video. The text-plus-still combo is faster to triage than a 90-second clip without context.
- What is the right size for a bug-report PDF?
- Under 5 MB for easy email/ticket attachment. Compress screenshots — most can be JPEG at 80% quality with no perceptible loss. If the report is going over 10 MB, compress the PDF or split the screenshots to an appendix file. A bloated PDF gets opened slower and read less carefully.
Citations
- Wikipedia — “Bug tracking system — fields and report structure.” en.wikipedia.org/wiki/Bug_tracking_system
- GitHub Docs — “About issues — guidance on writing a good report.” docs.github.com/en/issues/tracking-your-work-with-issues/about-issues
Make engineers want to read your bug
Merge steps + environment + screenshots into a single PDF in the browser — engineers triage it the same day.
Build a one-PDF bug report →