Media

Use media effectively while managing maintenance burden.

This page explains best practices for using screenshots, GIFs, and videos in your documentation.

Screenshots, GIFs, and videos enhance documentation but require maintenance as UI changes. Use them selectively to minimize upkeep.

Key guidelines:

• Keep media supplementary: If text explains a workflow clearly, skip visuals.
• Ensure accessibility: Add alt text for images, subtitles for videos, and transcripts for audio. Accessible content benefits all users.
• Balance value with maintenance: UI changes quickly outdate screenshots and videos. Consider whether update effort matches added value.

When to use media

• Screenshots: Tasks difficult to explain with words alone.
• GIFs: Short complex workflows or promotional content.
• Videos: Abstract concepts and lengthy workflows.

Use media sparingly and intentionally. Effective media enhances comprehension without creating maintenance burdens or accessibility barriers.