Cómo usar imágenes, capturas y videos en la documentación
Aprende cuándo y cómo usar capturas, GIFs y videos en la documentación, con orientación sobre formato, texto alternativo y mantenimiento a largo plazo.
Los medios visuales pueden hacer que los flujos de trabajo complejos sean más claros que solo el texto, pero conllevan un costo de mantenimiento. Cada captura de pantalla que publicas es un compromiso de actualizarla cuando la interfaz cambie. Cada video queda desactualizado cuando el flujo que muestra cambia.
El objetivo no es evitar los medios. Es usarlos deliberadamente, para que la claridad que aportan supere el trabajo de mantenerlos actualizados.
No todos los pasos necesitan una captura de pantalla. No todos los conceptos necesitan un diagrama. Antes de agregar medios, pregúntate si el contenido es realmente más claro con ellos o si una prosa limpia y ejemplos de código servirían igual de bien a los usuarios.
Usa capturas de pantalla para tareas que son difíciles de describir con palabras, especialmente flujos de trabajo centrados en la interfaz donde los usuarios necesitan orientarse visualmente, o donde identificar el elemento correcto de la interfaz sería ambiguo sin verlo.
Evita las capturas de pantalla para:
- Acciones simples que los usuarios no pueden confundir fácilmente (“haz clic en Guardar”)
- Contenido que cambia frecuentemente: páginas de configuración, paneles de control e interfaces con muchas funciones son costosas de mantener
- Propósitos decorativos donde la imagen no aporta información
Los GIFs funcionan bien para demostraciones cortas en bucle: mostrar una animación, revelar una interacción de varios pasos o capturar un flujo de trabajo que es más fácil de seguir visualmente que describir paso a paso.
Mantén los GIFs cortos. Los archivos de más de unos segundos se vuelven grandes y lentos de cargar, y los GIFs largos son más difíciles de seguir para los usuarios que un video corto que pueden pausar y rebobinar.
Usa videos para conceptos abstractos que se benefician de la narración, o para flujos de trabajo largos donde la secuencia y el tiempo importan. Los videos son más accesibles que los GIFs para contenido complejo: los usuarios pueden pausar, rebobinar y controlar la velocidad de reproducción.
Aloja los videos en una plataforma externa como YouTube o Loom e incrústalos en lugar de servir archivos de video directamente. Los archivos de video aumentan significativamente los tiempos de carga de la página.
- Usa PNG para capturas de pantalla y diagramas. PNG preserva bordes nítidos y texto.
- Usa WebP para fotografías o imágenes donde el tamaño del archivo importa. WebP es más pequeño que PNG y JPEG con una calidad comparable.
- Usa GIF solo cuando la animación sea necesaria. Para imágenes estáticas, GIF no ofrece ventajas sobre PNG.
- Comprime las imágenes antes de agregarlas a tu repositorio. Herramientas como Squoosh reducen el tamaño de los archivos sin pérdida visible de calidad.
- Mantén las capturas de pantalla en su resolución nativa o reduce su tamaño; nunca las amplíes, ya que esto introduce borrosidad.
- El ancho estándar de la documentación es típicamente de 800–1200px. Las capturas de pantalla más anchas se reducen automáticamente, pero pueden verse pequeñas en dispositivos móviles.
- Recorta las capturas de pantalla ajustándolas al área relevante de la interfaz. El cromo circundante, el espacio vacío y los elementos no relacionados distraen de lo que estás mostrando.
Cada imagen necesita texto alternativo descriptivo. El texto alternativo hace que las imágenes sean accesibles para los usuarios de lectores de pantalla y contribuye al SEO.
Escribe texto alternativo que describa lo que muestra la imagen y por qué es importante en contexto:
<!-- Descriptivo y contextual -->
<!-- No es útil -->
Consulta Accesibilidad para más información sobre cómo escribir texto alternativo efectivo.
Usa nombres de archivo descriptivos en kebab-case que indiquen el contenido:
api-keys-settings.png ✓
screenshot-2024-01-15.png ✗
image1.png ✗Los nombres de archivo descriptivos facilitan encontrar y reemplazar imágenes desactualizadas, y contribuyen marginalmente al SEO de imágenes.
Los medios son la parte más costosa de mantener en la documentación. Un solo rediseño de la interfaz puede hacer que docenas de capturas de pantalla queden desactualizadas simultáneamente.
Algunas prácticas que reducen la carga de mantenimiento:
- Recorta ajustándote al elemento relevante. Las capturas de pantalla que muestran solo el componente que se está discutiendo quedan desactualizadas más lentamente que las capturas de página completa que incluyen navegación, encabezados y la interfaz circundante.
- Evita las capturas de pantalla para contenido que cambia frecuentemente. Si una página de configuración recibe cambios de interfaz cada trimestre, considera si una prosa descriptiva es más mantenible que una captura de pantalla.
- Conserva los archivos fuente. Almacena los originales sin comprimir o los archivos con capas cuando sea posible, para que puedas actualizar las capturas de pantalla sin tener que recapturarlas desde cero.
- Documenta lo que muestra cada imagen. Un comentario en el MDX o un manifiesto de imágenes compartido que indique qué contenido representa una imagen hace más rápido identificar recursos desactualizados durante la revisión.