Image Optimization for Documentation Sites

Documentation images have a different job from marketing images. They are not only visual decoration. They explain steps, show interface states, clarify diagrams, and help users complete tasks. If optimization makes a screenshot hard to read or a diagram too blurry, the page may become smaller while the documentation becomes worse.

A good documentation image workflow balances file size with clarity. It preserves source captures, uses the right format for each asset, and reviews images at the size readers actually see.

"Convert docs images to WebP for faster pages" is incomplete advice. Documentation quality depends on whether a reader can still follow the task, read labels, understand diagrams, and trust that screenshots match the current product.

Classify Documentation Images#

Most documentation sites contain several image types:

• UI screenshots
• cropped interface states
• diagrams
• architecture drawings
• code editor screenshots
• terminal screenshots
• product photos
• icons and logos

These should not all use the same rule. A product photo may work well as lossy WebP. A diagram may be better as SVG. A screenshot with small text may need PNG or high-quality WebP.

Create a docs image inventory before converting:

This classification is the editorial control. Without it, a batch conversion can make a documentation site look faster while making it less useful.

Crop Before Compressing#

Many documentation screenshots are full-screen captures when the user only needs one panel, button, or setting. Cropping can improve both file size and comprehension.

A cropped screenshot:

• removes irrelevant UI
• keeps important text larger
• reduces pixels before compression
• focuses the reader on the action

Do the crop before WebP conversion. Compression cannot fix a screenshot where the relevant label is too small to read.

Use a crop note in the pull request:

Source: sources/billing-fullscreen.png
Output: optimized/billing-payment-method.webp
Crop reason: only the Payment method panel is relevant
Reader size: 720 px content column on desktop, full width on mobile
Text review: labels readable without opening the image separately

That note is small, but it proves the image was edited for comprehension rather than only for byte savings.

Preserve Source Screenshots#

Keep original screenshots in a source folder. Documentation changes over time, and screenshots often need to be updated when the product UI changes. If the only remaining file is a compressed output, future edits may require a new capture or a lower-quality re-export.

Use a structure like:

docs-images/
  sources/
  optimized/

The source folder can contain PNG captures, design exports, or diagram source files. The optimized folder contains web-ready outputs.

If using GetWebP CLI for the optimized folder, keep conversion separate from source capture:

npx -y getwebp ./docs-images/sources \
  -o ./docs-images/optimized \
  --recursive \
  --format webp \
  --quality 90 \
  --json > ./docs-images/reports/conversion.ndjson

The GetWebP CLI command reference documents --output, --recursive, --format, --quality, and --json. It also states that original files are never modified or deleted. For documentation sites, that source-preservation detail is not incidental; it is what makes future screenshot updates practical.

Do not feed every docs asset to the same command. The GetWebP supported input table covers raster formats such as JPG/JPEG, PNG, BMP, WebP, HEIC/HEIF, and AVIF. Vector SVG diagrams should usually stay in the diagram workflow, not be treated as raster screenshots.

Review at Reader Size#

Documentation images should be reviewed inside the docs page, not just in a file viewer. Check desktop and mobile layouts. If an image is placed in a narrow content column, text may become unreadable even if the source screenshot is sharp.

Review:

• UI labels
• button text
• code snippets
• terminal commands
• diagram labels
• arrows and callouts
• dark mode screenshots

If users need to read the text, do not approve an output that forces zooming unless the page intentionally provides a zoom interaction.

Use a review table:

This is where file-size-only guidance fails. A 45 percent smaller screenshot that makes a CLI flag unreadable is a documentation regression.

Choose Format by Asset#

Use SVG for diagrams and icons when they are truly vector-based. Use PNG when pixel-exact text and flat UI details are more important than file size. Use WebP for photos and many screenshots after visual review.

Google's WebP documentation explains WebP's lossy, lossless, and transparency capabilities. MDN's SVG documentation is useful when deciding whether a diagram should remain vector.

A practical format decision table:

The strongest optimization for a command or code sample is often not image compression. It is replacing the screenshot with real text and using an image only for the UI context around it.

Avoid Re-Encoding Old Outputs#

Documentation sites often accumulate old images. Before running a broad conversion, identify which files are source captures and which are already optimized outputs. Re-encoding an old compressed screenshot can make text worse.

When in doubt, regenerate from the source screenshot or recapture the current UI.

Use structured output to catch suspicious rows. The GetWebP JSON output reference documents NDJSON results with fields such as outputPath, originalSize, newSize, savedRatio, quality, qualityMode, and status.

Rows that deserve manual review:

Do not hide these rows in a summary average.

Version Images With Product Changes#

When the product UI changes, update screenshots deliberately instead of replacing files silently. A filename such as billing-settings-2025-11.webp can be clearer than reusing an old path when the image shows a different interface.

This helps reviewers match documentation text to the visible UI. It also reduces cache confusion when readers or support teams still see older screenshots.

Keep a small mapping file:

page	image	product_version	source_capture	optimized_output	reviewed_by
/docs/billing	billing-payment-method.webp	2025.11	sources/billing-fullscreen.png	optimized/billing-payment-method.webp	Docs

That record makes screenshot drift visible. If support reports that docs do not match the UI, the team can trace which product version the image represented.

Keep Alt Text Useful#

Documentation image alt text should support the task. For a screenshot, describe the relevant interface state rather than every visual detail. For a diagram, summarize the relationship the diagram explains or provide nearby text that covers the same information.

Image optimization should not remove or duplicate alt text. If a build step replaces image markup, inspect the generated HTML.

An alt text review should go beyond checking whether an alt attribute exists. Ask whether the reader can still complete the task:

If image markup is generated by a docs framework, verify the final HTML after optimization. The optimized file path should change; the accessibility meaning should not.

Add Image Review to Docs Updates#

Every documentation update that changes screenshots should include image review:

1. capture or update the source image
2. crop to the relevant area
3. generate optimized output
4. review in the docs page
5. preserve the source
6. verify alt text

This keeps optimization tied to editorial quality.

Add the conversion evidence to the PR:

Command: npx -y getwebp ./docs-images/sources -o ./docs-images/optimized --recursive --format webp --quality 90 --json
Report: docs-images/reports/conversion.ndjson
Images changed: 14
Rejected after review: 2 screenshots
Kept as SVG: 5 diagrams
Alt text checked: yes
Mobile docs page checked: yes

The rejected screenshots matter. They show that the team is not treating every smaller output as a better documentation asset.

For documentation sites, clarity is the performance budget's constraint. Smaller files are useful only when readers can still follow the instructions without strain.