This article covers guidelines for how to use 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. Over 2 billion people use assistive technology, and accessibility features benefit 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.
The following table contains media guidelines & time required to update, courtesy of Idan Englander, Manager of Technical Writing at Anaconda:
Media TypeWhen to useExampleTime
ScreenshotsFor tasks that are difficult to explain with wordsUI element (such as a button or dropdown) is hidden or obscure~5 min
GIFsFor promotional purposes and short yet complex workflowsProduct changelog~1 hour
VideosFor abstract concepts and long workflowsTutorialsSeveral hours
Use media sparingly and intentionally to avoid unnecessary documentation debt. When done right, it enhances comprehension without adding maintenance burdens or accessibility barriers.