Passer au contenu principal
Lorsque vous créez une documentation accessible, vous privilégiez une conception du contenu qui la rend utilisable par le plus grand nombre, quel que soit le moyen d’accès et la manière d’interagir avec elle. La documentation accessible améliore l’expérience utilisateur pour tous. Votre contenu est plus clair, mieux structuré et plus facile à parcourir. Ce guide propose quelques bonnes pratiques pour créer une documentation accessible, mais il n’est pas exhaustif. Considérez l’accessibilité comme un processus continu. Les technologies et les normes évoluent avec le temps, offrant de nouvelles opportunités d’améliorer la documentation.

​
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 ». 
<!-- Good -->
Découvrez comment [configurer votre navigation](/organize/navigation).

<!-- Unclear relation between  -->
[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 : 
| Fonctionnalité | Statut |
| -------------- | ------ |
| Recherche | Actif |
| Analytics | Actif |

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

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

​
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

  • Écrivez en langage simple.
  • Définissez les termes techniques lors de leur première occurrence.
  • Évitez les phrases à rallonge.
  • Employez la voix active.

​
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
  • Hiérarchie des titres incorrecte
  • Contraste des couleurs insuffisant
Lorsque l’analyse est terminée, passez en revue les problèmes signalés et corrigez-les dans votre objet. Exécutez de nouveau la commande pour valider vos corrections.

​
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 :

​
Ressources supplémentaires

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