Compressing Screenshots for Documentation

Aggressive JPEG compression puts blurry rings around 12 px UI text. Crop to the panel that proves the step, then use an optimized PNG or a high-quality WebP so labels stay readable. Start with Crop Image. A full-screen retina PNG includes the menu bar, the dock, and the wallpaper, and the wiki often shows that image at half the width.

An internal "Getting Started" page weighed 14 MB, mostly PNG screenshots exported at native retina resolution with no crop. New hires on hotel Wi-Fi waited thirty seconds for images that displayed at half that width anyway.

A documentation screenshot is there to show a step. It should load quickly and include the pixels that explain the step.

Why the files get huge

• Full-screen captures that include the menu bar, the dock, and the desktop wallpaper
• Retina 2x exports that were never downscaled. See Retina Images 2x Explained
• PNG as the default from Snipping Tool or macOS, which is lossless and heavy when the shot is photographic
• An animated GIF of a screen recording, where MP4 or an animated WebP would be smaller
• The same image pasted into new versions without replacing the old file

A sequence that holds

1. Capture the step

Frame the smallest region that proves the step. Hide notifications. Use a consistent browser zoom (100%) so the UI matches what readers see.

2. Crop before you compress

Remove chrome the reader does not need. Crop Image handles a quick crop without Photoshop.

Social crops follow different ratios. A docs screenshot cares about whether the UI is readable, which is a different goal from the ratios in Crop Images for Social Media.

3. Resize to the display size

If the docs render images at 720px wide, export 1080 to 1440px at most for retina, not 3840px.

Use Resize Image with the aspect ratio locked.

4. Pick a format

| Content | Format | Notes | | --- | --- | --- | | UI, code, dialogs | PNG or lossless WebP | Sharp edges | | Blurred backgrounds, photos | WebP or JPEG | Smaller file | | Dark mode UI | PNG. Watch banding | See the dark mode screenshot guide |

WebP vs JPG and PNG vs JPG Guide cover the tradeoffs.

5. Compress, then look

Run the file through Compress Image. Compare at 100% zoom. If button labels fuzz, reduce the compression or crop more.

How Image Compression Affects Quality explains the artifact patterns.

6. Annotate after the file is the right size

Add arrows and callouts after compression so you are not re-exporting a bloated master. Some tools bake annotations into the PNG. Flatten once, at the final size.

Where the file is going

GitHub README: prefer a relative path in the repo, and keep images under 1 MB so a clone from far away stays practical. Use a width attribute if the markdown allows HTML.

Confluence or Notion: upload the optimized file. Pasting from the clipboard sends the full-resolution capture.

PDF handouts: compress images before you assemble them with JPG to PDF. See How to Compress a PDF.

Slack or Teams: compress before you share. Those apps recompress, and a second pass makes an already damaged screenshot worse.

Dark mode

Dark UI screenshots band in gradients and crush shadows. Read Dark Mode Screenshots: PNG Settings for export settings that keep contrast.

Names and versions

Pair the export with Batch Renaming Before Upload:

docs-checkout-step-03-payment-form-v2.webp

A version suffix keeps a wiki editor from embedding a CDN URL you later delete.

Accessibility

• Alt text should describe the action in the image, not the word "screenshot"
• Do not rely on color alone in annotations. Add numbers or labels
• If the text inside the image is essential, repeat the key steps in the prose (WCAG)

Large doc sets

Teams with 500 or more screenshots:

• A folder-watch script with pngquant or cwebp
• A CI check that fails a pull request adding an image over 300 KB
• One source of Figma exports at a defined scale

A browser tool is the better fit for an ad hoc pass while you write a single article.

Export defaults

Windows Snipping Tool defaults to PNG. Capture a region, not the full screen. macOS Command-Shift-4 saves a PNG to the desktop. Rename it immediately. ShareX can set the output folder and a naming template. Chrome DevTools can capture a node, which crops to that element and suits component docs.

Images in version control

Store optimized images in Git LFS if the repo is growing large. Otherwise commit WebP files under 200 KB directly. Reference them with relative paths in MDX. A broken image in the docs does more damage than a file that is slightly large.

Localization

If the docs ship in more than one language, capture the UI in each locale. Do not paint replacement text over the screenshot. Use a filename suffix such as _en or _ur, as in Batch Image Convert Naming.

Limitations

Aggressive lossy JPEG compression creates blurry ringing around 12 px UI text. Crop tightly around the relevant panel and use an optimized PNG or a high-quality WebP so the labels stay crisp.

Crop, size the file to the layout, and compress it. Run the export through Compress Image before the wiki upload. A 14 MB getting-started page is what an uncropped retina PNG set costs the reader.