Screenshots for Documentation and Bug Reports

Format is not a close call here

A screenshot is composed of flat areas of uniform colour and abrupt high-contrast edges where text and interface borders sit. That is the content PNG compresses best and JPEG handles worst, and the gap is not marginal.

JPEG works by discarding fine high-frequency detail, and a letter edge is almost entirely high-frequency detail. Discarding it leaves the edge to be reconstructed from what remains, producing the halo of disturbed pixels around text that makes compressed screenshots look grubby. PNG stores the pixels exactly, so text stays as crisp as it was on screen.

The file size usually favours PNG too, which surprises people who assume lossy always means smaller. Our own measured test on a sharp-text image found 33,657 bytes as optimized PNG against 49,875 bytes as JPEG at quality 70 — larger, and visibly worse. Flat graphics with text are PNG territory on both counts.

The exception is a screenshot that is mostly photograph — a screen capture of a video, or a page dominated by a large image. There, the content is photographic and JPEG or WebP is reasonable. Judge by what is in the frame, not by the fact that it came from a screen.

Capturing at the right size

Capture only the region that matters. Every operating system offers a region-capture shortcut, and using it saves the cropping step and keeps the file small. A full-screen capture of a 4K display to show one dialog box wastes both bytes and the reader's attention.

Do not scale a screenshot up afterwards. Text on a screen is rendered at a specific pixel size; enlarging it interpolates between those pixels and produces soft, smeared letters. If the text is too small to read in the final document, capture it larger at source — zoom the application, increase its font size, or use a higher display scaling setting — rather than enlarging the image.

Scaling down is safer but still costs legibility. A screenshot reduced to half size has its text rendered at half size, and below a certain point it becomes decorative rather than readable. If a screenshot must appear small in a document, consider cropping tighter instead so the remaining content can stay at full size.

On high-density displays, captures come out at the physical pixel count rather than the layout size, so a capture of a 600-pixel-wide dialog may be 1200 pixels. That is fine and often desirable; just be aware of it when a size limit applies.

Cropping and framing

Include enough context for the reader to locate what you are showing. A button in isolation is ambiguous; the same button with the panel around it is identifiable. Somewhere between those two is the right crop, and it depends on how familiar the reader is with the interface.

Remove everything that is not doing work. Browser chrome, unrelated panels, empty space, and the desktop behind the window all dilute attention. A tightly framed screenshot reads faster than a wide one with an arrow pointing into it.

For a sequence of steps, keep the framing consistent between images. Screenshots of the same panel captured at slightly different sizes and positions make the reader re-orient at each step, and the inconsistency reads as carelessness.

If the interface will change, consider whether the screenshot is the right medium at all. Screenshots date badly, and documentation illustrated heavily with them becomes wrong faster than documentation written in text. Use them where the visual arrangement genuinely matters and text where it does not.

The privacy check

This is the part that actually costs people something, and it takes ten seconds. Before sharing any screenshot, look at every part of the frame rather than at the thing you meant to capture.

The usual leaks: browser tabs revealing what else you have open, bookmark bars with personal or client site names, notification banners arriving mid-capture, an email client preview pane showing subject lines and senders, file paths containing your name or an employer's, account names and avatars in a corner, and calendar entries in a sidebar.

Redact properly. Drawing a black rectangle over text in an image editor and flattening the result is safe. Applying a blur is not always safe — heavily pixelated or blurred text has been reconstructed successfully in some circumstances, and a light blur is trivially readable when zoomed. A solid opaque shape is the reliable choice.

Never redact by covering something in a tool that preserves layers, then exporting a format that keeps them. Flatten the image and verify the output file, not the editing canvas. The same applies to cropping in a viewer that stores the original alongside the crop.

Metadata is less of a risk for screenshots than for photographs, since a screen capture has no GPS coordinates. It may still record the device and software, and prepared copies written without metadata cost nothing.

Annotation that helps

Annotation should direct attention, not decorate. One arrow or one box around the relevant element is usually enough. Three arrows, a circle, and two colours of highlighting turn the image into a puzzle.

Use a colour that contrasts with the interface and stays consistent across a document. Bright red or orange works against most neutral interfaces; a subtle grey outline disappears.

Number the steps when a single screenshot shows a sequence, and match those numbers to the text. This is far clearer than describing positions in prose, and it survives translation.

Keep annotations outside the content where possible — a box around an element rather than a mark on top of it — so the reader can still see what they are being shown.

Screenshots in bug reports

A screenshot shows what happened; it rarely shows why. The useful bug report pairs the image with the information the image cannot carry: what you did immediately before, what you expected, what actually occurred, the application version, and the operating system and browser.

Capture the whole error, including any identifier or code. A cropped screenshot showing only the words 'something went wrong' is considerably less useful than one including the reference number underneath it.

Where the problem is a sequence or a timing issue, a short screen recording communicates more than several stills. Where the problem is text — a log, a stack trace, an error message — paste the text rather than a picture of it. Text can be searched, copied, and diffed; a screenshot of text cannot, and it forces whoever is helping you to retype it.

That last point is the most commonly ignored and the most appreciated when followed.

Publishing screenshots accessibly

A screenshot is unreadable to anyone using a screen reader, and the text inside it is invisible to search and untranslatable. The alt text must carry what the image contributes — for an error message, that means including the message itself.

Do not rely on a screenshot to convey a step. Write the step in text and use the screenshot to confirm it visually. A reader following instructions on a phone, or with images disabled, or listening rather than looking, then still gets the procedure.

For a complex screenshot such as a filled-in form or a settings panel, describing every field in alt text is impractical. Summarise what it shows in the alt text and put the details in the surrounding prose, where they are available to everyone.