Comment créer une documentation accessible

Lorsque vous créez une documentation accessible, vous privilégiez une conception de contenu qui rend votre documentation utilisable par le plus grand nombre, quel que soit le moyen d’accès ou la manière dont les personnes interagissent avec elle.

Une documentation accessible améliore l’expérience de toutes et tous. Votre contenu est plus clair, mieux structuré et plus facile à parcourir, que les utilisateurs y accèdent avec un lecteur d’écran, la navigation au clavier, un appareil mobile ou des connexions réseau lentes.

Ce guide présente les bonnes pratiques pour une documentation accessible. L’accessibilité est un processus continu. Les technologies et les normes évoluent, et il y a toujours des opportunités d’amélioration. Commencez par les changements à fort impact et intégrez l’accessibilité à votre flux de travail.

L’accessibilité (parfois abrégée en a11y, pour le nombre de lettres entre la première et la dernière lettre d’« accessibility ») consiste à concevoir et à développer, de manière intentionnelle, des sites web et des outils utilisables par le plus grand nombre. Les personnes ayant un handicap temporaire ou permanent doivent bénéficier du même niveau d’accès aux technologies numériques. Concevoir pour l’accessibilité profite à tout le monde, y compris aux personnes qui consultent votre site web sur mobile ou via des réseaux lents.

Une documentation accessible respecte les normes d’accessibilité du web, principalement les Web Content Accessibility Guidelines (WCAG). Ces directives aident à garantir que votre contenu est perceptible, opérable, compréhensible et robuste.

Rendre votre documentation accessible est un processus. Vous n’avez pas à tout corriger d’un coup et ce n’est pas quelque chose que l’on fait une seule fois.

Si vous commencez tout juste à mettre en place des pratiques d’accessibilité pour votre documentation, envisagez une approche progressive : commencez par les changements à fort impact, puis étoffez progressivement.

Voici trois actions que vous pouvez entreprendre dès maintenant pour améliorer l’accessibilité de votre documentation :

1. Exécutez mint a11y pour identifier les problèmes d’accessibilité dans votre contenu.
2. Ajoutez un texte alternatif (alt text) à toutes les images.
3. Vérifiez la hiérarchie des titres pour garantir un seul H1 par page et des titres qui se suivent dans l’ordre.

Le meilleur flux de travail est celui qui convient à votre équipe. Voici une approche possible de l’accessibilité :

Phase 1 : Images et structure

• Passez en revue toutes les images pour vérifier la présence d’un texte alternatif descriptif.
• Passez en revue les textes de lien et remplacez les formules génériques comme « cliquez ici ».
• Corrigez les problèmes de hiérarchie des titres dans l’ensemble de votre documentation.

Phase 2 : Navigation et médias

• Testez la navigation au clavier sur votre documentation.
• Testez la compatibilité avec les lecteurs d’écran.
• Ajoutez des sous-titres et des transcriptions aux vidéos intégrées.
• Vérifiez le contraste des couleurs.

Phase 3 : Intégrez-la à votre flux de travail

• Exécutez mint a11y avant de publier un nouveau contenu.
• Intégrez des vérifications d’accessibilité à votre processus de relecture de contenu.
• Testez la navigation au clavier lors de l’ajout de fonctionnalités interactives.
• Vérifiez que les nouveaux liens externes et contenus intégrés incluent des titles et descriptions appropriés.

Commencer modestement et intégrer l’accessibilité à votre flux de travail habituel la rend pérenne. Chaque amélioration aide davantage d’utilisateurs à accéder avec succès à votre documentation.

Un contenu bien structuré est plus facile à parcourir et à comprendre, surtout pour les utilisateurs de lecteurs d’écran qui s’appuient sur les titres pour se déplacer dans les pages, ainsi que pour les personnes qui utilisent la navigation au clavier.

Chaque page doit comporter un seul titre H1, qui provient de la propriété title: dans le frontmatter de la page. Utilisez ensuite les niveaux de titres dans l’ordre sans en sauter. Par exemple, ne passez pas de H2 à H4.

<!-- Bon -->
# Titre de la page (H1)

## Section principale (H2)

### Sous-section (H3)

### Autre sous-section (H3)

## Autre section principale (H2)

<!-- Mauvais -->
# Titre de la page (H1)

## Section principale (H2)

#### Sous-section (H4)

### Autre sous-section (H3)

Les titres d’un même niveau doivent avoir des noms uniques.

<!-- Bon -->
## Conseils d'accessibilité (H2)

### Rédiger un texte alternatif efficace (H3)

### Utiliser un contraste de couleur approprié (H3)

<!-- Mauvais -->
## Conseils d'accessibilité (H2)

### Conseil (H3)

### Conseil (H3)

Le texte du lien doit être explicite et refléter la destination. Évitez les formulations vagues comme « cliquez ici » ou « en savoir plus ».

<!-- Bon -->
Découvrez comment [configurer votre navigation](/organize/navigation).

<!-- Relation peu claire entre le texte du lien et la destination -->
[En savoir plus](/organize/navigation).

• Scindez les longs paragraphes.
• Utilisez des listes pour les étapes et les options.
• Mettez en avant les informations avec des encadrés.

N’utilisez les tableaux qu’avec parcimonie et uniquement pour des données tabulaires dont la signification découle des en-têtes de colonnes et de lignes.

Lorsque vous utilisez des tableaux, incluez des en-têtes afin que les lecteurs d’écran puissent associer les données à la bonne colonne :

| Fonctionnalité | Statut | Dernière mise à jour |
| -------------- | ------ | -------------------- |
| Recherche  | Actif | 2024-03-15   |
| Analytics | Actif | 2024-03-10 |
| Exports | Bêta | 2024-03-20 |

L’exemple médiocre n’a pas d’en-têtes, ce qui empêche les lecteurs d’écran d’annoncer ce que représente chaque colonne.

Le texte alternatif rend les images accessibles aux utilisateurs de lecteurs d’écran et s’affiche lorsque les images ne se chargent pas. Les images de votre documentation doivent comporter un texte alternatif qui décrit l’image et précise clairement pourquoi vous l’avez incluse. Même avec un texte alternatif, ne vous fiez pas uniquement aux images pour transmettre des informations. Assurez-vous que votre contenu décrit ce que l’image communique.

• Soyez précis : Décrivez ce que montre l’image, pas seulement que c’est une image.
• Soyez concis : Contentez-vous d’une à deux phrases.
• Évitez les redondances : Ne commencez pas par « Image de » car les lecteurs d’écran savent déjà que le texte alternatif appartient à une image. En revanche, incluez des formulations comme « Capture d’écran de » ou « Schéma de » si ce contexte est important pour l’image.

<!-- Bon -->
![Capture d'écran du Dashboard montrant trois projets actifs et deux invitations en attente](/images/dashboard.png)

<!-- Pas utile -->
![Capture d'écran du Dashboard](/images/dashboard.png)

Pour les images en Markdown, ajoutez un texte alternatif entre crochets :

![Description de l'image](/path/to/image.png)

Pour les images HTML, utilisez l’attribut « alt » :

<img
  src="/images/screenshot.png"
  alt="Panneau de paramètres avec les options d'accessibilité activées. Les options sont mises en évidence par un rectangle orange."
/>

Les iframes et les vidéos intégrées doivent avoir des titres descriptifs :

<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutoriel : Configuration de votre premier site de documentation"
></iframe>

Les choix de conception visuelle influencent l’accessibilité de votre documentation pour les personnes ayant une basse vision, un daltonisme ou d’autres déficiences visuelles.

Si vous personnalisez les couleurs de votre thème, vérifiez que les taux de contraste respectent les exigences WCAG :

• Texte courant : taux de contraste minimal de 4,5:1
• Texte large : taux de contraste minimal de 3:1
• Éléments interactifs : taux de contraste minimal de 3:1

Testez le mode light et le mode sombre. La commande mint a11y vérifie le contraste des couleurs.

{
  "colors": {
    "primary": "#0066CC",
    "background": {
      "light": "#FFFFFF",
      "dark": "#1A1A1A"
    }
  }
}

Dans l’exemple insuffisant, le jaune (#FFCC00) sur blanc présente un contraste insuffisant. L’arrière-plan en mode sombre (#333333) est trop clair pour une lisibilité optimale.

Si vous utilisez la couleur pour transmettre une information, ajoutez également un libellé textuel ou une icône. Par exemple, ne signalez pas les erreurs uniquement avec du texte rouge. Ajoutez une icône d’erreur ou le mot « Erreur ».

• Rédigez dans un langage simple.
• Définissez les termes techniques lors de leur première utilisation.
• Évitez les phrases trop longues.
• Utilisez la voix active.

Les code blocks sont un élément essentiel de la documentation technique, mais ils nécessitent des considérations d’accessibilité spécifiques pour que les utilisateurs de lecteurs d’écran puissent les comprendre. De manière générale, suivez ces recommandations :

• Divisez les longs exemples de code en sections plus petites et cohérentes.
• Commentez la logique complexe dans le code.
• Envisagez de fournir une description textuelle pour les algorithmes complexes.
• Lors de la présentation d’une arborescence de fichiers, utilisez de vrais code blocks avec des labels de langage plutôt que de l’art ASCII.

Déclarez toujours la langue pour la coloration syntaxique. Cela aide les lecteurs d’écran à annoncer le contexte du code aux utilisateurs :

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

Fournissez un contexte clair pour les code block :

La fonction suivante récupère les données utilisateur depuis l'API :

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

Cela retourne une promesse qui se résout vers l'objet utilisateur.

Les vidéos, animations et autres contenus multimédias doivent être accompagnés d’alternatives textuelles afin que tous les utilisateurs puissent accéder aux informations qu’ils contiennent.

Les sous-titres rendent le contenu vidéo accessible aux personnes sourdes ou malentendantes. Ils aident aussi les utilisateurs dans des environnements sensibles au bruit ainsi que les personnes non natives :

• Utilisez des sous-titres pour tout le contenu parlé des vidéos.
• Incluez les effets sonores pertinents dans les sous-titres.
• Assurez-vous que les sous-titres sont synchronisés avec l’audio.
• Utilisez une ponctuation appropriée et identifiez les locuteurs lorsque plusieurs personnes parlent.

La plupart des plateformes d’hébergement vidéo permettent d’ajouter des sous-titres. Importez des fichiers de sous-titres ou utilisez des sous-titres générés automatiquement comme point de départ, puis vérifiez leur exactitude.

Les transcriptions offrent un autre moyen d’accéder au contenu vidéo. Elles sont consultables par recherche, plus faciles à référencer et accessibles aux lecteurs d’écran :

<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutoriel : Configuration de l'authentification"
></iframe>

<Accordion title="Transcription vidéo">
Dans ce tutoriel, nous allons voir comment configurer l'authentification...
</Accordion>

Placez les transcriptions à proximité de la vidéo ou fournissez un lien clair pour y accéder.

Si des informations essentielles ne figurent que dans une vidéo :

• Fournissez les mêmes informations sous forme de texte.
• Ajoutez des captures d’écran clés avec un texte alternatif descriptif.
• Rédigez un tutoriel qui couvre la même matière.

Ainsi, les utilisateurs qui n’ont pas accès au contenu vidéo peuvent tout de même mener à bien leur tâche.

Des tests réguliers vous aident à repérer les problèmes d’accessibilité avant que les utilisateurs ne les rencontrent.

Utilisez la commande d’interface en ligne de commande (CLI) mint a11y pour analyser automatiquement votre documentation à la recherche de problèmes d’accessibilité courants :

mint a11y

La commande vérifie :

• Texte alternatif manquant pour les images et les vidéos.
• Contraste des couleurs insuffisant.

Une fois l’analyse terminée, un rapport similaire au suivant s’affiche :

Accessibility Issues Found:

❌ Missing alt text (3 issues)
  - /guides/quickstart.mdx:45 - Image missing alt text
  - /api-reference/users.mdx:12 - Image missing alt text
  - /guides/setup.mdx:89 - Video missing title attribute

⚠️  Color contrast (2 issues)
  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)

✅ 0 issues found in 15 other pages

Texte alternatif manquant : Ajoutez un texte alternatif descriptif à l’image ou à la vidéo :

<!-- Avant -->
![](/images/dashboard.png)

<!-- Après -->
![Dashboard montrant trois projets actifs et deux invitations en attente](/images/dashboard.png)

Échecs de contraste de couleurs : Mettez à jour les couleurs de votre thème dans docs.json :

{
  "colors": {
    "primary": "#0066CC",  // Modifié depuis #FFCC00
    "light": "#3399FF",
    "dark": "#004C99"
  }
}

Exécutez à nouveau mint a11y pour valider vos corrections.

Utilisez des flags pour vérifier des problèmes d’accessibilité spécifiques :

# Vérifier uniquement les textes alternatifs manquants
mint a11y --skip-contrast

# Vérifier uniquement les problèmes de contraste des couleurs
mint a11y --skip-alt-text

# Faire échouer le pipeline CI/CD si des problèmes sont détectés
mint a11y --fail-on-error

Parcourez votre documentation en utilisant uniquement votre clavier :

1. Appuyez sur Tab pour avancer dans les éléments interactifs.
2. Appuyez sur Shift + Tab pour revenir en arrière.
3. Appuyez sur Enter pour activer les liens et les boutons.
4. Vérifiez que tous les éléments interactifs sont accessibles et affichent un indicateur de focus visible.

Pour des évaluations plus complètes :

• Lecteurs d’écran : Testez avec NVDA (Windows) ou VoiceOver (Mac).
• Extensions de navigateur : Installez axe DevTools ou WAVE pour analyser les pages et détecter les problèmes.
• Directives WCAG : Consultez les Web Content Accessibility Guidelines pour connaître les normes détaillées.

Approfondissez vos connaissances en accessibilité avec ces ressources de confiance :

• WebAIM : articles et tutoriels pratiques sur l’accessibilité du web
• The A11y Project : ressources communautaires et liste de vérification sur l’accessibilité
• W3C Web Accessibility Initiative (WAI) : normes officielles et recommandations en matière d’accessibilité