Creating Better Screenshots for Bug Reports

A valuable screenshot for a bug report offers more than just proof of an issue. It helps others quickly identify the affected application, understand the conditions leading to the problem, and connect the visual information with written reproduction steps.

Typically, the best report combines a brief description, exact instructions, expected and actual behaviors, environment details, and focused visual evidence. A screenshot supports this information; it cannot stand alone.

Elements of a Comprehensive Bug Report

A useful bug report generally contains:

• A clear, descriptive title.
• Numbered instructions to reproduce the issue.
• What you expected to happen.
• What actually happened.
• Whether the issue is constant or intermittent.
• Versions of the application, operating system, browser, and any relevant dependencies.
• A simple, reproducible example, if feasible.
• Supporting evidence like screenshots, recordings, logs, or stack traces.

This framework aligns with current recommendations for software feedback and issue management. GitHub's guidelines for issue reporting advocate for separating reproduction steps, expected and actual behavior, environment details, and additional evidence. Similarly, Microsoft's documentation on problem reporting emphasizes providing clear reproduction steps and pertinent diagnostic information.GitHub issue guidance Microsoft problem-reporting guidance

Provide sufficient context

A screenshot showing only a mysterious red icon might be impossible to understand. Conversely, a full multi-monitor desktop view could reveal too much irrelevant information, making the actual problem difficult to pinpoint.

Ensure your context addresses these points:

• Which application or page is this related to?
• What specific panel, dialog, or control is affected?
• What action seemed to precede the issue?
• Where is the problem located?

If it's a dialog error, include the entire dialog box along with enough of the parent window to identify the specific task. For layout problems, show the affected component and adjacent elements to illustrate alignment or overflow issues. In a browser context, capture the relevant page area, but omit unrelated tabs, bookmarks, profiles, or extensions unless they are directly part of the bug report.

With ShareX, Capture → Regionis generally the most effective starting point. Theregion capture guidedetails how to select an area and proceed with configured capture tasks.

Keep the exact error message

If an application displays an error, ensure its visible text is included in the screenshot. Whenever possible, also copy the error text directly into the report.

Text is searchable, selectable, accessible, and easier for maintainers to reference. Screenshots of logs or terminal output often complicate investigation because the text cannot be searched or copied, and crucial lines might be cut off.

Use ShareX OCRIf the text cannot be directly copied, always verify the OCR-generated output against the original image before submitting it. Optical Character Recognition can often introduce mistakes in punctuation, file paths, identifiers, and code.

For extensive log files, attach them as a text file or copy-paste only the relevant portion, adhering to the project's contribution guidelines. Always remember to remove sensitive information like tokens, personal directory paths, and secrets beforehand.

Add Annotations with a Clear Goal

Annotations should aim to minimize the effort required to comprehend an image.

Helpful annotation types include:

• An arrow pointing to the specific control that is not behaving as expected.
• A rectangular outline around an area displaying an incorrect layout.
• A numbered marker that corresponds to the written steps for reproduction.
• A brief label indicating the expected versus the actual regions of the issue.
• A highlight placed behind a critical line of text.
• Magnification for a visual flaw that is genuinely difficult to see.

Avoid cluttering the evidence with overly large arrows, repetitive circles, humorous additions, or lengthy text blocks. Always retain the original, unedited screen capture until the problem is resolved, in case a maintainer requires details that might have been cropped or obscured.

The ShareX image editorThis tool offers features such as arrows, shapes, text, numbered steps, highlights, magnification, spotlight, cropping, blurring, and pixelation. Select an annotation color that is consistently high-contrast and use the fewest markings possible.

Align Screenshots with Reproduction Steps

If a problem requires several actions to manifest, the images provided should follow the same sequence as the written steps.

Consider this example:

1. Open Settings.
2. Select Notifications.
3. Disable Show task completion notification.
4. Capture a selected region.
5. Observe that a notification still appears after the action.

Typically, the most useful image would display both the deactivated setting and the unexpected notification, if both can be captured without creating confusion. If separate images are necessary, label them as 'Step 3' and 'Step 5' instead of submitting an unorganized collection.

Do not include screenshots for steps that are already obvious and functioning correctly. Each image should clarify a point that the accompanying text alone cannot adequately explain.

Illustrate Expected vs. Actual Behavior

Clearly articulate the difference:

• Expected:No completion notification appears following the capture.
• Actual:The system shows a confirmation message in the bottom-right portion of the screen.

If the intended layout exists elsewhere, a side-by-side image can be very useful. Ensure both views are clearly labeled and maintain a consistent scale. Do not modify the actual screenshot to match the expected outcome.

When reporting a regression, include the last known functional version if you have confirmed it. Do not assume an earlier release worked without explicit testing.

Provide Environment Details

Visual evidence can change based on the environment. Include relevant information such as:

• The specific Windows version and edition.
• The application's version and build type.
• The browser name and its version number.
• Display scaling and resolution, particularly for layout or capture issues.
• The quantity and arrangement of connected monitors.
• Any active theme, language setting, or right-to-left layout.
• The graphics hardware or driver, for problems related to rendering or recording.
• Whether the application is running with administrative privileges.
• Any relevant extensions, plugins, or accessibility settings in use.

Only include details that are relevant to the problem. A full list of hardware isn't needed for a typo, but display scale is crucial for a coordinate error or a high-DPI capture flaw.

Use a Brief Recording for Motion and Timing

A static image cannot convey a flicker, an animation, a delayed response, the path of a cursor, a drag operation, or a sequence that fails only at a specific instant.

When a short recording significantly improves reproducibility, use one. TheShareX screen recording guideexplains how to record a Windows region as video or a GIF.

Keep bug recordings concise:

• Begin just before the first relevant user action.
• Show the cursor's movement if it's important.
• Pause briefly once the unexpected outcome is visible.
• Avoid unnecessary setup and spoken commentary.
• Ensure your report always includes written reproduction steps.

Rather than multiple minutes of unorganized screen activity, a focused, thirty-second recording is typically more helpful.

Erase Private and Sensitive Information

Prior to attaching any image or video file, check it for the following:

• Profile photos, names, and email addresses.
• API keys, access tokens, passwords, and recovery codes.
• Server names, internal URLs, and IP addresses.
• Financial data, customer data, or health details.
• Browser bookmarks, open tabs, chat messages, and notifications.
• File paths showing user or organization names.
• Session identifiers, QR codes, or barcodes.

Whenever feasible, crop out private content. While blurring and pixelation are useful visual tools, cropping completely eliminates the pixels. After making edits, zoom in and carefully inspect the final file.

If a secret has already appeared in a public issue, remove the attachment if possible and immediately rotate or revoke the secret. Simply deleting an image doesn't guarantee that it wasn't viewed, cached, or downloaded by someone.

Security vulnerabilities should be reported following the project's private disclosure process, not a public bug tracker. For ShareX, refer to the instructions provided in thesecurity policy.

A Reliable ShareX Bug Report Method

Here is one practical configuration:

1. Set up a dedicated hotkey for region capture.
2. Enable Open in image editor.
3. Leave automatic upload turned off by default.
4. Capture the relevant part of the application.
5. Add one or two precise annotations.
6. Crop or redact any private content.
7. Save the image to your computer using a descriptive filename.
8. Review it at its full size.
9. Attach it to your report, along with written steps and environment specifics.

Should your issue tracker demand links rather than direct attachments, opt for a dedicated, deliberate upload process instead of automatically uploading every capture. Theautomatic screenshot upload guideexplains how to set up a destination and then copy the resulting URL.

Bug Report Template

The template below is concise yet provides investigators with a helpful structure:

Title:
A specific summary of the unexpected behavior

Steps to reproduce:
1.
2.
3.

Expected result:

Actual result:

Frequency:
Every time / intermittent / happened once

Environment:
- Application version:
- Windows version:
- Other relevant configuration:

Evidence:
- Annotated screenshot:
- Short recording, if timing matters:
- Relevant logs or error text:

Additional notes:

Always search for existing reports before creating a new one, and if the project offers its own issue template, use that.

Common Screenshot Errors

Capturing the Entire Desktop

This frequently reveals private information and makes the defect hard to locate. Only capture the relevant application area, unless the bug involves monitor arrangement or desktop context.

Cropping Too Closely

An image showing only a single button or error icon might lack the necessary application and workflow context for investigation.

Substituting Written Steps with a Video

Maintainers should not need to repeatedly view a recording to figure out precise actions. Always include numbered text as well.

Posting Screenshots of Code or Logs

Whenever feasible, provide copyable text or a minimal repository example. Only use an image when the visual presentation itself is crucial.

Over-annotating

Too many shapes and labels can obscure the interface's actual state. Highlight only the fewest, most important details.

Uploading Without Reviewing

Automatic sharing happens so quickly that private content can be published before you notice. Always review evidence locally, especially when recording audio or video.

Final Checklist

Before submitting your report, verify the following:

• The title addresses one problem.
• The reproduction steps can be followed by another person.
• Explicit expected and actual behaviors are present.
• Relevant version and environment details are included.
• Context and the specific problem area are both visible in screenshots.
• Where feasible, reproduce error messages as actual text.
• Annotations serve to clarify, not to obscure, the evidence.
• Any sensitive information has been removed.
• Recordings are only included if movement or timing is crucial.
• Confirm the issue does not already exist within the project.