Saltar al contenido principal
Cuando creas documentación accesible, priorizas un diseño de contenido que hace que tu documentación sea utilizable por la mayor cantidad de personas posible, sin importar cómo accedan o interactúen con ella. La documentación accesible mejora la experiencia de usuario para todos. Tu contenido es más claro, está mejor estructurado y es más fácil de navegar. Esta guía ofrece algunas prácticas recomendadas para crear documentación accesible, pero no es exhaustiva. Debes considerar la accesibilidad como un proceso continuo. Las tecnologías y los estándares cambian con el tiempo, lo que abre nuevas oportunidades para mejorar la documentación.

​
¿Qué es la accesibilidad?

La accesibilidad (a veces abreviada como a11y por el número de letras entre la primera y la última de “accessibility”) consiste en diseñar y crear intencionalmente sitios web y herramientas que puedan utilizar el mayor número posible de personas. Las personas con discapacidades temporales o permanentes deben tener el mismo nivel de acceso a las tecnologías digitales. Y diseñar con la accesibilidad en mente beneficia a todos, incluidas las personas que acceden a tu sitio web desde dispositivos móviles o redes lentas. La documentación accesible sigue los estándares de accesibilidad web, principalmente las Pautas de Accesibilidad para el Contenido Web (WCAG). Estas pautas ayudan a garantizar que tu contenido sea perceptible, operable, comprensible y sólido.

​
Introducción a la accesibilidad

Hacer que tu documentación sea accesible es un proceso. No tienes que solucionarlo todo de una vez ni puedes hacerlo solo una vez. Si recién empiezas a implementar prácticas de accesibilidad en tu documentación, considera un enfoque por fases: comienza con cambios de alto impacto y avanza a partir de allí.

​
Primeros pasos

Estas son tres acciones que puedes realizar ahora mismo para mejorar la accesibilidad de tu documentación:
  1. Ejecuta mint a11y para identificar problemas de accesibilidad en tu contenido.
  2. Añade texto alternativo a todas las imágenes.
  3. Revisa la jerarquía de encabezados para asegurarte de que haya un H1 por página y que los encabezados sigan un orden secuencial.

​
Planifica tu trabajo de accesibilidad

El mejor flujo de trabajo es el que mejor se adapta a tu equipo. Aquí tienes una forma de abordar el trabajo de accesibilidad: Fase 1: Imágenes y estructura
  • Revisa todas las imágenes para asegurarte de que tengan texto alternativo descriptivo.
  • Revisa el texto de los enlaces y reemplaza frases genéricas como “haz clic aquí”.
  • Corrige problemas en la jerarquía de encabezados en toda tu documentación.
Fase 2: Navegación y medios
  • Prueba la navegación con el teclado en tu documentación.
  • Prueba la compatibilidad con lectores de pantalla.
  • Agrega subtítulos y transcripciones a los videos incrustados.
  • Revisa el contraste de color.
Fase 3: Incorpóralo a tu flujo de trabajo
  • Ejecuta mint a11y antes de publicar contenido nuevo.
  • Incluye comprobaciones de accesibilidad en tu proceso de revisión de contenido.
  • Prueba la navegación con el teclado al agregar funciones interactivas.
  • Verifica que los nuevos enlaces externos y los contenidos incrustados incluyan títulos y descripciones adecuados.
Empezar poco a poco e integrar la accesibilidad en tu flujo de trabajo habitual la hace sostenible. Cada mejora ayuda a que más personas accedan a tu documentación con éxito.

​
Estructura tu contenido

El contenido bien estructurado es más fácil de navegar y comprender, especialmente para las personas que usan lectores de pantalla y dependen de los encabezados para desplazarse por las páginas, así como para quienes navegan con el teclado.

​
Usa una jerarquía adecuada de encabezados

Cada página debe tener un solo encabezado H1, definido por la propiedad title: en el frontmatter de la página. Usa los demás encabezados en orden, sin saltarte niveles. Por ejemplo, no pases de H2 a H4. 
<!-- Bueno -->
# Título de página (H1)

## Sección principal (H2)

### Subsección (H3)

### Otra subsección (H3)

## Otra sección principal (H2)

<!-- Malo -->
# Título de página (H1)

## Sección principal (H2)

#### Subsección (H4)

### Otra subsección (H3)
Los encabezados del mismo nivel deben tener nombres únicos. 
<!-- Bueno -->
## Consejos de accesibilidad (H2)

### Escribir texto alternativo efectivo (H3)

### Usar contraste de color adecuado (H3)

<!-- Malo -->
## Consejos de accesibilidad (H2)

### Sugerencia (H3)

### Sugerencia (H3)

​
Escribe texto de enlace descriptivo

El texto del enlace debe ser significativo y estar relacionado con el destino. Evita frases vagas como “haz clic aquí” o “leer más”. 
<!-- Bueno -->
Aprende cómo [configurar tu navegación](/organize/navigation).

<!-- Relación poco clara entre  -->
[Más información](/organize/navigation).

​
Mantén el contenido fácil de recorrer

  • Divide los párrafos largos.
  • Usa listas para pasos y opciones.
  • Destaca la información con avisos.

​
Usa una estructura de tabla adecuada

Usa las tablas con moderación y solo para datos tabulares cuyo significado provenga de los encabezados de columnas y filas. Cuando uses tablas, incluye encabezados para que los lectores de pantalla puedan asociar los datos con la columna correcta: 
| Función | Estado |
| ------- | ------ |
| Búsqueda  | Activa |
| Analytics | Activa |

​
Escribe texto alternativo descriptivo

El texto alternativo hace que las imágenes sean accesibles para las personas que usan lectores de pantalla y aparece cuando las imágenes no se cargan. Las imágenes en tu documentación deben incluir texto alternativo que describa la imagen y deje claro por qué está incluida. Incluso con texto alternativo, no debes depender únicamente de las imágenes para transmitir información. Asegúrate de que tu contenido describa lo que comunica la imagen.

​
Escribe texto alternativo eficaz

  • Sé específico: Describe lo que muestra la imagen, no solo que es una imagen.
  • Sé conciso: Limítate a una o dos frases.
  • Evita redundancias: No empieces con “Imagen de” porque los lectores de pantalla ya saben que el texto alternativo está asociado a una imagen. Sin embargo, incluye descripciones como “Captura de pantalla de” o “Diagrama de” si ese contexto es importante para la imagen.
<!-- Bueno -->
![Captura de pantalla del dashboard que muestra tres proyectos activos y dos invitaciones pendientes](/images/dashboard.png)

<!-- No es útil -->
![Captura de pantalla del dashboard](/images/dashboard.png)

​
Añade texto alternativo a las imágenes

Para las imágenes en Markdown, incluye el texto alternativo entre corchetes: 
![Descripción de la imagen](/path/to/image.png)
Para las imágenes en HTML, usa el atributo alt: 
<img
  src="/images/screenshot.png"
  alt="Panel de configuración con opciones de accesibilidad activadas. Las opciones están destacadas con un rectángulo naranja."
/>

​
Añade títulos al contenido incrustado

Los iframes y las inserciones de video requieren títulos descriptivos: 
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Configuración de tu primer sitio de documentación"
></iframe>

​
Diseña para mejorar la legibilidad

Las decisiones de diseño visual afectan cuán accesible es tu documentación para personas con baja visión, daltonismo u otras discapacidades visuales.

​
Asegúrate de un contraste de color suficiente

Si personalizas los colores del tema, verifica que las relaciones de contraste cumplan los requisitos de las WCAG:
  • Texto de párrafo: relación de contraste mínima de 4.5:1
  • Texto grande: relación de contraste mínima de 3:1
  • Elementos interactivos: relación de contraste mínima de 3:1
Prueba tanto el modo claro como el oscuro. El comando mint a11y comprueba el contraste de color.

​
No dependas solo del color

Si usas el color para transmitir información, incluye también una etiqueta de texto o un icon. Por ejemplo, no marques los errores únicamente con texto rojo. Incluye un icono de error o la palabra “Error”.

​
Usa un lenguaje claro y conciso

  • Escribe en lenguaje sencillo.
  • Define los términos técnicos la primera vez que los uses.
  • Evita las oraciones largas o enrevesadas.
  • Utiliza la voz activa.

​
Haz que los ejemplos de código sean accesibles

Los bloques de código son una parte fundamental de la documentación técnica, pero requieren consideraciones específicas de accesibilidad para garantizar que las personas que usan lectores de pantalla puedan comprenderlos. En general, sigue estas pautas:
  • Divide los ejemplos de código largos en fragmentos más pequeños y con sentido.
  • Comenta la lógica compleja dentro del código.
  • Considera proporcionar una descripción en texto para algoritmos complejos.
  • Al mostrar la estructura de archivos, usa bloques de código reales con etiquetas de lenguaje en lugar de arte ASCII.

​
Especifica el lenguaje de programación

Declara siempre el lenguaje para el resaltado de sintaxis. Esto ayuda a los lectores de pantalla a anunciar el contexto del código a los usuarios: 
```javascript
function obtenerDatosUsuario(id) {
  return fetch(`/api/users/${id}`);
}
```

​
Proporciona contexto del código

Proporciona contexto claro para los bloques de código: 
La siguiente función obtiene datos de usuario desde la API:

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

Esto devuelve una promesa que se resuelve en el objeto de usuario.

​
Accesibilidad de vídeo y multimedia

Los vídeos, las animaciones y otros contenidos multimedia necesitan alternativas textuales para que todas las personas puedan acceder a la información que contienen.

​
Agrega subtítulos a los videos

Los subtítulos hacen que el contenido de video sea accesible para personas sordas o con discapacidad auditiva. También ayudan a quienes están en entornos sensibles al sonido y a hablantes no nativos:
  • Usa subtítulos para todo el contenido hablado en los videos.
  • Incluye efectos de sonido relevantes en los subtítulos.
  • Asegúrate de que los subtítulos estén sincronizados con el audio.
  • Usa puntuación adecuada e identifica a los interlocutores cuando hablen varias personas.
La mayoría de las plataformas de alojamiento de videos admiten subtítulos. Sube archivos de subtítulos o usa subtítulos generados automáticamente como punto de partida y luego revísalos para verificar su precisión.

​
Proporciona transcripciones

Las transcripciones ofrecen una forma alternativa de acceder al contenido de video. Se pueden buscar, son más fáciles de consultar y accesibles para los lectores de pantalla: 
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Configuración de autenticación"
></iframe>

<Accordion title="Transcripción del video">
En este tutorial, veremos cómo configurar la autenticación...
</Accordion>
Coloca las transcripciones junto al video o proporciona un enlace claro para acceder a ellas.

​
Considera alternativas al contenido exclusivamente en video

Si la información crítica solo aparece en un video:
  • Proporciona la misma información en formato de texto.
  • Incluye capturas de pantalla clave con texto alternativo descriptivo.
  • Crea un tutorial escrito que cubra el mismo material.
Esto garantiza que los usuarios que no pueden acceder al contenido en video puedan igualmente completar su tarea.

​
Prueba tu documentación

Probar con regularidad te ayuda a detectar problemas de accesibilidad antes de que los usuarios se encuentren con ellos.

​
Detecta problemas de accesibilidad con mint a11y

Usa el comando de la CLI mint a11y para analizar automáticamente tu documentación en busca de problemas de accesibilidad comunes: 
mint a11y
El comando verifica:
  • Falta de texto alternativo en imágenes
  • Jerarquía incorrecta de encabezados
  • Contraste de color insuficiente
Cuando finalice el análisis, revisa los problemas detectados y corrígelos en tu contenido. Ejecuta el comando de nuevo para verificar tus correcciones.

​
Prueba básica de navegación con teclado

Navega por tu documentación usando solo el teclado:
  1. Pulsa Tab para avanzar por los elementos interactivos.
  2. Pulsa Shift + Tab para retroceder.
  3. Pulsa Enter para activar enlaces y botones.
  4. Comprueba que todos los elementos interactivos sean accesibles y tengan indicadores de foco visibles.

​
Profundiza en las pruebas de accesibilidad

Para realizar pruebas más completas:

​
Recursos adicionales

Sigue aprendiendo sobre accesibilidad con estos recursos de confianza:
⌘I