Comment créer une documentation accessible

Créez une documentation accessible en suivant les directives WCAG avec un HTML sémantique, la navigation au clavier, le texte alternatif et des pratiques de contenu inclusives.

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.

​

Qu’est-ce que l’accessibilité ?

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.

​

Premiers pas avec l’accessibilité

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.

​

Premiers pas

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.

​

Planifiez votre travail en matière d’accessibilité

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.

​

Structurez votre contenu

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.

​

Utilisez une hiérarchie de titres correcte

Chaque page doit comporter un seul titre H1, défini par 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)

​

Rédigez un texte de lien descriptif

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

​

Facilitez le survol du contenu

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

​

Utilisez une structure de tableau appropriée

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 :

Bonne structure de tableau

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

​

Rédiger un texte alternatif descriptif

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 elle est 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.

Pour en savoir plus sur l’utilisation des images, consultez le guide des médias.

​

Rédigez un texte alternatif efficace

• 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 est associé à 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)

​

Ajouter un texte alternatif aux images

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."
/>

​

Ajouter des titres au contenu intégré

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>

​

Concevoir pour la lisibilité

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.

​

Assurez un contraste de couleurs suffisant

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.

Exemple de bon contraste

{
  "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.

​

Ne vous fiez pas uniquement à la couleur

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

​

Utilisez un langage clair et concis

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

Consultez le guide de style et de ton pour découvrir d’autres bonnes pratiques de rédaction.

​

Rendre les exemples de code accessibles

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.

​

Indiquez le langage de programmation

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}`);
}
```

​

Fournir du contexte autour du code

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.

​

Accessibilité des vidéos et des contenus multimédias

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.

​

Ajouter des sous-titres aux vidéos

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.

​

Fournir des transcriptions

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.

​

Envisagez des alternatives au contenu exclusivement vidéo

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.

​

Testez votre documentation

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

​

Vérifiez les problèmes d’accessibilité avec mint a11y

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.

​

Interpréter le résultat

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

​

Corriger les problèmes courants

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 des vérifications ciblées

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

​

Test de base de la navigation au clavier

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.

​

Approfondissez vos tests d’accessibilité

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.

​

Foire aux questions

Ma documentation doit-elle être conforme à WCAG AA ou AAA ?

La plupart des organisations visent la conformité WCAG 2.1 niveau AA, qui constitue la norme pour de nombreuses obligations légales et offre un bon équilibre entre accessibilité et faisabilité. Le niveau AAA est plus exigeant et n’est pas toujours réalisable pour tous les types de contenu.

Commencez par le niveau AA comme référence. La commande mint a11y vérifie les exigences courantes du niveau AA, comme le contraste des couleurs et le texte alternatif.

Comment tester ma documentation avec un lecteur d'écran ?

Sur Mac, utilisez VoiceOver intégré (appuyez sur Cmd + F5 pour l’activer). Sur Windows, téléchargez NVDA (gratuit et open source). Parcourez votre documentation en n’utilisant que le lecteur d’écran et écoutez si les titres sont annoncés correctement, si les textes de lien sont descriptifs, si les images ont un texte alternatif et si l’ordre de lecture est logique. Pas besoin d’être expert pour repérer les principaux problèmes.

Quelle est la différence entre le texte alternatif et les légendes d'image ?

Le texte alternatif est lu par les lecteurs d’écran et s’affiche lorsque les images ne se chargent pas. Il décrit ce que montre l’image et pourquoi elle est pertinente. Le texte alternatif est obligatoire pour l’accessibilité.

Les légendes apparaissent sous les images pour tous les utilisateurs. Elles fournissent un contexte supplémentaire, l’attribution ou une explication. Les légendes sont facultatives et complètent le texte alternatif.

Utilisez les deux lorsqu’une image nécessite à la fois une description (texte alternatif) et un contexte supplémentaire (légende).

Puis-je utiliser des emojis dans une documentation accessible ?

Oui, mais avec parcimonie. Les lecteurs d’écran annoncent à voix haute le nom des emojis ; plusieurs emojis à la suite deviennent donc gênants. Par exemple, 🎉 devient « party popper » et 🚀 devient « rocket », si bien que 🎉 🚀 devient « party popper rocket ». Évitez d’utiliser des emojis pour transmettre des informations essentielles. Si l’emoji était supprimé, le sens devrait rester clair. En cas de doute, préférez le texte.

Comment gérer l'accessibilité des exemples de code ?

Indiquez le langage sur chaque code block pour la coloration syntaxique. Apportez du contexte avant et après les code blocks afin que les utilisateurs de lecteurs d’écran comprennent ce que fait le code, car les lecteurs d’écran survolent souvent le code lui-même. Divisez les longs exemples en plus petits morceaux et utilisez des noms de variables descriptifs qui ont du sens à l’oral.

Que faire si je ne peux pas corriger tous les problèmes d'accessibilité immédiatement ?

Priorisez par impact. Corrigez en premier le texte alternatif manquant, la navigation au clavier défaillante et le contraste des couleurs insuffisant : ce sont les problèmes qui touchent le plus d’utilisateurs. Viennent ensuite la mauvaise hiérarchie des titres et les textes de lien vagues. Documentez les problèmes connus avec un plan pour les traiter. Le progrès vaut mieux que la perfection.

​

Ressources supplémentaires

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é