Skip to main content
This page explains best practices for using screenshots, GIFs, and videos in your documentation.
Screenshots, GIFs, and videos can enhance documentation but require ongoing maintenance as UI elements change. Use them selectively to avoid unnecessary upkeep. Key guidelines:
  • Media should be supplementary. If a workflow is clear in text alone, avoid adding visuals.
  • Ensure accessibility. Add alt text for images, subtitles for videos, and transcripts for audio content. Many people use assistive technology and accessibile content benefits all users.
  • Balance clarity with maintainability. Frequent UI changes can make screenshots and videos outdated quickly. Consider whether the effort to update them is worth the value they add.

​
When to use media

  • Screenshots for tasks that are difficult to explain with words.
  • GIFs for promotional purposes and short yet complex workflows.
  • Videos for abstract concepts and long workflows.
Use media sparingly and intentionally to avoid unnecessary documentation debt. When done right, it enhances comprehension without adding maintenance burdens or accessibility barriers.
⌘I