| title | description |
|---|---|
Using Media |
Guidelines for incorporating media |
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 Type | When to use | Example | Time |
|---|---|---|---|
| Screenshots | For tasks that are difficult to explain with words | UI element (such as a button or dropdown) is hidden or obscure | ~5 min |
| GIFs | For promotional purposes and short yet complex workflows | Product changelog | ~1 hour |
| Videos | For abstract concepts and long workflows | Tutorials | Several hours |
Use media sparingly and intentionally to avoid unnecessary documentation debt. When done right, it enhances comprehension without adding maintenance burdens or accessibility barriers.