Compressing Screenshots for Documentation

The internal wiki's "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 width anyway.

Documentation screenshots are communication, not archival. They should load fast and show the right pixels — not every pixel on your monitor.

Why doc screenshots get huge

• Full-screen captures including menu bar, dock, and desktop wallpaper
• Retina 2x exports never downscaled — see Retina Images 2x Explained
• PNG defaults from Snipping Tool / macOS — lossless but heavy for photos
• Animated GIF screen recordings where MP4 or WebP animation would be smaller
• Pasted repeatedly across versions without replacing old assets

Workflow that sticks

1. Capture with intent

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

2. Crop before compress

Remove chrome readers don't need. The Crop Image tool handles quick crops without opening Photoshop.

For social-style crops the ratios differ — doc screenshots prioritize content legibility over aspect ratio rules in Crop Images for Social Media.

3. Resize to display size

If your docs render images at 720px wide, export 1080–1440px max for retina — not 3840px.

Use Resize Image with locked aspect ratio.

4. Choose format deliberately

| Content | Format | Notes | | --- | --- | --- | | UI, code, dialogs | PNG or WebP lossless | Sharp edges | | Blurred backgrounds, photos | WebP or JPEG | Lower size | | Dark mode UI | PNG — watch banding | See dark mode screenshot guide |

WebP vs JPG and PNG vs JPG Guide cover trade-offs.

5. Compress iteratively

Run through Compress Image. Compare at 100% zoom — if button labels fuzz, reduce compression strength or crop more.

How Image Compression Affects Quality explains artifact patterns.

6. Annotate after optimization

Arrows and callouts added after compression prevent re-exporting bloated masters. Some tools bake annotations into PNG — flatten once at final size.

Platform-specific tips

GitHub README — Prefer relative paths in repo; keep images under 1 MB for international clones. Use width HTML if markdown allows.

Confluence / Notion — Re-upload optimized versions; don't paste from clipboard at full resolution.

PDF handouts — Compress images before JPG to PDF assembly; see How to Compress a PDF.

Slack / Teams — Compress before sharing; platforms recompress anyway and double-artifact ugly screenshots.

Dark mode documentation

Dark UI screenshots need different handling — banding in gradients, crushed shadows. Read Dark Mode Screenshots — PNG Settings for export settings that preserve contrast.

Naming and versioning

Pair with Batch Renaming Before Upload:

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

Version suffixes prevent wiki editors from embedding deleted CDN URLs.

Accessibility in docs

• Alt text describing the action shown, not "screenshot"
• Don't rely on color alone in annotations — add numbers or labels
• Text in images — if critical, repeat key steps in prose (WCAG)

Automation for large doc sets

Teams with 500+ screenshots:

• Folder watch script with pngquant or cwebp
• CI check failing PRs that add images over 300 KB
• Single source in Figma exports at defined scale

Browser tools remain best for ad hoc passes when writing a single article.

Troubleshooting

What is the best format for documentation screenshots? PNG for UI with sharp text and flat colors. JPEG or WebP for photo-heavy screenshots with gradients. Avoid BMP and uncompressed TIFF for web docs.

How much should I compress documentation screenshots? Aim for under 200 KB per full-width screenshot when possible, under 100 KB for partial crops. If text becomes blurry, back off compression or crop tighter to the relevant UI.

Should I resize screenshots before uploading to Confluence or Notion? Yes. Match display width — uploading 4K captures when the page renders at 800px wastes storage and slows page load. Resize to 1.5–2x display width for retina clarity.

Limitations

When not to use this approach

Conclusion

Documentation screenshots should be cropped, right-sized, and compressed — not forensic dumps of your entire desktop.

Capture less, show more. Run exports through Compress Image before the wiki upload button. Your readers' bandwidth is not unlimited.

Tool-specific export defaults

Windows Snipping Tool — PNG default; switch region capture not fullscreen. macOS Cmd+Shift+4 — PNG to desktop; rename immediately. ShareX — configure default output folder and naming template. Chrome DevTools — capture node screenshot crops element only — excellent for component docs.

Version control for doc images

Store optimized images in git LFS if repo grows large; otherwise commit WebP under 200 KB directly. Reference images with relative paths in MDX — broken image links in docs erode trust faster than slightly large files.

Localization screenshots

If docs ship in multiple languages, capture UI in each locale — don't Photoshop text overlays. Filename suffix _en, _ur per Batch Image Convert Naming.