Screenshots and Documentation Images: Optimization Guide

Screenshots and documentation images have unique requirements: they must be crisp, readable, and optimized for fast loading. This guide covers best practices for creating and optimizing images for technical documentation.

Format Selection

When to Use Each Format

Content Type	Best Format	Why
UI screenshots	PNG or WebP	Crisp text, exact colors
Code screenshots	PNG	No compression artifacts
Diagrams	SVG	Scales perfectly
Annotated screenshots	PNG	Preserves overlay quality
Full-page captures	WebP	Good compression, quality
Terminal output	SVG or PNG	Crisp monospace text

PNG vs WebP for Screenshots

Factor	PNG	WebP
Text sharpness	Excellent	Excellent
File size	Larger	30-50% smaller
Browser support	Universal	96%+
Transparency	Yes	Yes

Recommendation: Use WebP with PNG fallback for broad compatibility.

Capture Best Practices

Resolution Guidelines

Display Target	Capture Resolution	Notes
Standard docs	1x	Smallest files
Retina docs	2x	Sharp on HiDPI
Responsive	1.5x	Good balance

# macOS: Capture at 2x
screencapture -x screenshot@2x.png

# Display at 1x in HTML

<img
  src="screenshot@2x.png"
  alt="Settings panel"
  width="800"
  height="600"
>

Consistent Dimensions

Establish standard sizes for your documentation:

Screenshot Type	Dimensions
Full window	1200×800
Dialog/modal	600×400
Menu/dropdown	300×200
Inline UI element	Varies

Window Preparation

Before capturing:

• Clean up desktop/browser tabs
• Use consistent window size
• Remove personal information
• Use neutral/default theme
• Reset zoom to 100%

Annotation Best Practices

Callout Styles

/* Consistent annotation styling */
.callout-box {
  border: 2px solid #ef4444;
  border-radius: 4px;
}

.callout-number {
  background: #ef4444;
  color: white;
  border-radius: 50%;
  width: 24px;
  height: 24px;
  font-weight: bold;
}

.callout-arrow {
  stroke: #ef4444;
  stroke-width: 2px;
}

Annotation Guidelines

Element	Style
Highlight boxes	2px red border, no fill
Step numbers	Red circles with white text
Arrows	Red, 2px stroke
Text labels	Sans-serif, high contrast

Tools for Annotation

• Skitch (macOS) - Quick annotations
• Snagit - Professional features
• Greenshot (Windows) - Free, capable
• Figma/Sketch - Design-grade output
• CleanShot X (macOS) - Modern, feature-rich

Optimization Techniques

PNG Optimization

# Lossless optimization
optipng -o5 screenshot.png

# Lossy (significant savings)
pngquant --quality=80-95 screenshot.png -o screenshot-optimized.png

# Combine both
pngquant --quality=80-95 screenshot.png | optipng -o5 - > final.png

WebP Conversion

# Convert with high quality for text
cwebp -q 90 screenshot.png -o screenshot.webp

# Near-lossless for critical screenshots
cwebp -near_lossless 60 screenshot.png -o screenshot.webp

Sharp Script for Documentation Images

const sharp = require('sharp');

async function optimizeScreenshot(inputPath, outputDir) {
  const baseName = path.basename(inputPath, '.png');

  // Optimized PNG
  await sharp(inputPath)
    .png({ compressionLevel: 9, palette: true })
    .toFile(`${outputDir}/${baseName}.png`);

  // WebP version
  await sharp(inputPath)
    .webp({ quality: 90, nearLossless: true })
    .toFile(`${outputDir}/${baseName}.webp`);

  // Retina + 1x versions
  const metadata = await sharp(inputPath).metadata();

  if (metadata.width >= 1600) {
    await sharp(inputPath)
      .resize(Math.round(metadata.width / 2))
      .webp({ quality: 90 })
      .toFile(`${outputDir}/${baseName}-1x.webp`);
  }
}

Responsive Screenshots

Srcset for Documentation

<picture>
  <source
    srcset="screenshot.webp, screenshot@2x.webp 2x"
    type="image/webp"
  >
  <img
    src="screenshot.png"
    srcset="screenshot.png, screenshot@2x.png 2x"
    alt="Dashboard overview showing analytics panel"
    width="800"
    height="500"
    loading="lazy"
  >
</picture>

Dark/Light Mode Screenshots

<picture>
  <source
    srcset="screenshot-dark.webp"
    media="(prefers-color-scheme: dark)"
    type="image/webp"
  >
  <source
    srcset="screenshot-light.webp"
    type="image/webp"
  >
  <img
    src="screenshot-light.png"
    alt="Application settings"
  >
</picture>

Automation

Automated Screenshot Capture

Using Playwright:

const { chromium } = require('playwright');

async function captureScreenshot(url, outputPath, options = {}) {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  // Set viewport for consistent captures
  await page.setViewportSize({
    width: options.width || 1200,
    height: options.height || 800
  });

  await page.goto(url);

  // Wait for content to load
  await page.waitForLoadState('networkidle');

  // Capture screenshot
  await page.screenshot({
    path: outputPath,
    fullPage: options.fullPage || false
  });

  await browser.close();
}

// Usage
captureScreenshot('https://app.example.com/dashboard', 'dashboard.png');

CI/CD Integration

# .github/workflows/screenshots.yml
name: Update Screenshots

on:
  schedule:
    - cron: '0 0 * * 1' # Weekly
  workflow_dispatch:

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright
        run: npx playwright install chromium

      - name: Capture screenshots
        run: node scripts/capture-screenshots.js

      - name: Optimize screenshots
        run: node scripts/optimize-screenshots.js

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'docs: update screenshots'

Using Image CDNs

Sirv provides on-demand optimization:

<!-- Auto-optimized screenshot -->
<img
  src="https://your-site.sirv.com/docs/screenshot.png?format=optimal&q=90"
  alt="Configuration panel"
>

<!-- Responsive with CDN -->
<img
  src="https://your-site.sirv.com/docs/screenshot.png?w=800&format=webp"
  srcset="
    https://your-site.sirv.com/docs/screenshot.png?w=800&format=webp 1x,
    https://your-site.sirv.com/docs/screenshot.png?w=1600&format=webp 2x
  "
  alt="Configuration panel"
>

File Size Guidelines

Screenshot Type	Target Size	Max Size
Small UI element	10-30 KB	50 KB
Dialog/modal	30-80 KB	150 KB
Full window	80-200 KB	400 KB
Full page scroll	150-400 KB	800 KB
Annotated screenshot	50-150 KB	300 KB

Accessibility

Alt Text for Screenshots

<!-- Bad: Vague -->
<img src="settings.png" alt="Settings">

<!-- Good: Descriptive -->
<img
  src="settings.png"
  alt="Settings panel showing notification preferences with email alerts enabled and push notifications disabled"
>

Long Descriptions for Complex Screenshots

<figure>
  <img
    src="dashboard.png"
    alt="Analytics dashboard"
    aria-describedby="dashboard-desc"
  >
  <figcaption id="dashboard-desc">
    Dashboard showing: 1) Traffic graph in top-left with 25% weekly increase,
    2) User table in bottom section with 5 recent signups,
    3) Revenue chart in top-right showing $45,000 monthly total.
  </figcaption>
</figure>

Documentation Platform Tips

GitBook/Notion

• Use WebP for smaller bundle size
• Keep screenshots under 200KB
• Use consistent naming: feature-action.png

Docusaurus/VuePress

// Use the built-in image component
import Screenshot from '@site/static/img/screenshot.png';

<img src={Screenshot} alt="Feature overview" width="800" />

Markdown

![Settings panel showing notification preferences](./images/settings-notifications.png)

Conclusion

Optimizing documentation screenshots requires:

1. Consistent capture - Same dimensions, resolution, theme
2. Proper format - PNG/WebP for UI, SVG for diagrams
3. Smart annotation - Clear, consistent styling
4. Optimization - Compress without losing text clarity
5. Accessibility - Descriptive alt text

Use Sirv for automatic optimization and responsive delivery of documentation images.