Cómo usar imágenes, capturas y videos en la documentación - Mintlify

Los medios visuales en documentación

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.

Cuándo usar medios

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.

Capturas de pantalla

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.

GIFs

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.

Videos

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.

Directrices para cada tipo de medio

Formato y tamaño de archivo

• 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.

Dimensiones

• 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.

Texto alternativo

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.

Nomenclatura de archivos

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.

Mantenimiento

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.

Preguntas frecuentes

¿Debería usar capturas de pantalla o texto para instrucciones paso a paso?

Prefiere el texto con capturas de pantalla como complemento, no como reemplazo. El texto es más rápido de escanear, más fácil de buscar y más económico de actualizar. Agrega una captura de pantalla cuando los usuarios necesiten identificar visualmente algo en la interfaz o cuando un flujo de trabajo sería genuinamente confuso sin verlo. Un patrón común es describir el paso en texto e incluir una captura de pantalla solo para los pasos donde la orientación visual importa.

¿Cómo manejo las capturas de pantalla cuando se actualiza la interfaz?

La forma más rápida es recapturar las capturas de pantalla específicas que cambiaron en lugar de actualizar todo de una vez. Las capturas de pantalla recortadas ajustadamente que se enfocan en un solo elemento cambian con menos frecuencia que las capturas de página completa. Cuando se lanza un rediseño importante de la interfaz, trata las actualizaciones de capturas de pantalla como un sprint de documentación con un alcance definido en lugar de una distracción continua.

¿Cuál es la diferencia entre usar GIFs y videos cortos?

Los GIFs se reproducen en bucle automáticamente, no requieren interacción del usuario y se incrustan directamente en la página sin un reproductor. Funcionan bien para interacciones simples y cortas donde el bucle es útil. Los videos cortos son mejores para cualquier cosa que dure más de unos segundos, cualquier cosa que se beneficie del audio, o cualquier flujo de trabajo lo suficientemente complejo como para que los usuarios necesiten pausar y consultar fotogramas específicos. Los videos también tienen mejor soporte de accesibilidad: los GIFs no tienen control de pausa ni un equivalente de texto alternativo más allá de una descripción en el contenido circundante.

¿Necesito texto alternativo si la imagen es decorativa?

Si una imagen no aporta información, como un separador puramente decorativo o un elemento de fondo, usa un atributo alt vacío (alt="") para indicar a los lectores de pantalla que la omitan. Pero la mayoría de las imágenes en la documentación son informativas, no decorativas. En caso de duda, escribe texto alternativo.