Comment utiliser les images, captures d'écran et vidéos dans la documentation

Utilisez les captures d’écran, GIFs et vidéos efficacement dans la documentation avec des conseils sur le format, l’accessibilité et la maintenance à long terme.

Les médias visuels peuvent rendre les flux de travail complexes plus clairs que le texte seul, mais ils comportent un coût de maintenance. Chaque capture d’écran que vous publiez est un engagement à la mettre à jour lorsque l’interface change. Chaque vidéo devient obsolète lorsque le flux qu’elle montre change.

L’objectif n’est pas d’éviter les médias. C’est de les utiliser délibérément, pour que la clarté qu’ils apportent l’emporte sur le travail nécessaire pour les maintenir à jour.

​

Quand utiliser les médias

Chaque étape n’a pas besoin d’une capture d’écran. Chaque concept n’a pas besoin d’un diagramme. Avant d’ajouter des médias, demandez-vous si le contenu est véritablement plus clair avec eux ou si une prose soignée et des exemples de code serviraient tout aussi bien les utilisateurs.

​

Captures d’écran

Utilisez les captures d’écran pour les tâches difficiles à décrire avec des mots, en particulier les flux de travail centrés sur l’interface où les utilisateurs doivent s’orienter visuellement, ou lorsque l’identification du bon élément d’interface serait ambiguë sans le voir.

Évitez les captures d’écran pour :

• Les actions simples que les utilisateurs ne peuvent pas facilement confondre (“cliquez sur Enregistrer”)
• Le contenu qui change fréquemment : les pages de paramètres, les tableaux de bord et les interfaces riches en fonctionnalités sont coûteux à maintenir
• Les usages décoratifs où l’image n’apporte pas d’information

​

GIFs

Les GIFs fonctionnent bien pour les démonstrations courtes en boucle : montrer une animation, révéler une interaction en plusieurs étapes, ou capturer un flux de travail plus facile à suivre visuellement qu’à décrire étape par étape.

Gardez les GIFs courts. Les fichiers de plus de quelques secondes deviennent volumineux et lents à charger, et les GIFs longs sont plus difficiles à suivre pour les utilisateurs qu’une courte vidéo qu’ils peuvent mettre en pause et rembobiner.

​

Vidéos

Utilisez les vidéos pour les concepts abstraits qui bénéficient d’une narration, ou pour les longs flux de travail où la séquence et le timing comptent. Les vidéos sont plus accessibles que les GIFs pour le contenu complexe : les utilisateurs peuvent mettre en pause, rembobiner et contrôler la vitesse de lecture.

Hébergez les vidéos sur une plateforme externe comme YouTube ou Loom et intégrez-les plutôt que de servir directement des fichiers vidéo. Les fichiers vidéo augmentent considérablement les temps de chargement des pages.

​

Directives pour chaque type de média

​

Format et taille de fichier

• Utilisez PNG pour les captures d’écran et les diagrammes. PNG préserve les bords nets et le texte.
• Utilisez WebP pour les photographies ou les images où la taille du fichier compte. WebP est plus petit que PNG et JPEG avec une qualité comparable.
• Utilisez GIF uniquement lorsque l’animation est nécessaire. Pour les images statiques, GIF n’offre aucun avantage par rapport à PNG.
• Compressez les images avant de les ajouter à votre dépôt. Des outils comme Squoosh réduisent la taille des fichiers sans perte de qualité visible.

​

Dimensions

• Conservez les captures d’écran à leur résolution native ou réduisez-les — ne les agrandissez jamais, car cela introduit du flou.
• La largeur standard de la documentation est généralement de 800–1200px. Les captures d’écran plus larges sont réduites automatiquement mais peuvent paraître petites sur mobile.
• Recadrez les captures d’écran au plus près de l’interface pertinente. Le chrome environnant, l’espace vide et les éléments non liés détournent l’attention de ce que vous montrez.

​

Texte alternatif

Chaque image a besoin d’un texte alternatif descriptif. Le texte alternatif rend les images accessibles aux utilisateurs de lecteurs d’écran et contribue au SEO.

Rédigez un texte alternatif qui décrit ce que l’image montre et pourquoi c’est important dans le contexte :

<!-- Descriptif et contextuel -->
![La page de paramètres des clés API affichant une liste de trois clés actives avec leurs dates de création et horodatages de dernière utilisation](/images/api-keys-settings.png)

<!-- Pas utile -->
![Page de paramètres](/images/api-keys-settings.png)

Consultez Accessibilité pour en savoir plus sur la rédaction de texte alternatif efficace.

​

Nommage des fichiers

Utilisez des noms de fichiers descriptifs en kebab-case qui indiquent le contenu :

api-keys-settings.png       ✓
screenshot-2024-01-15.png   ✗
image1.png                  ✗

Les noms de fichiers descriptifs facilitent la recherche et le remplacement des images obsolètes, et contribuent marginalement au SEO des images.

​

Maintenance

Les médias sont la partie la plus coûteuse de la documentation à maintenir. Une seule refonte de l’interface peut rendre des dizaines de captures d’écran obsolètes simultanément.

Quelques pratiques qui réduisent la charge de maintenance :

• Recadrez au plus près de l’élément pertinent. Les captures d’écran qui montrent uniquement le composant en cours de discussion deviennent obsolètes plus lentement que les captures pleine page qui incluent la navigation, les en-têtes et l’interface environnante.
• Évitez les captures d’écran pour le contenu qui change fréquemment. Si une page de paramètres reçoit des modifications d’interface chaque trimestre, demandez-vous si une prose descriptive est plus maintenable qu’une capture d’écran.
• Conservez les fichiers sources. Stockez les originaux non compressés ou les fichiers en couches lorsque c’est possible, afin que les captures d’écran puissent être mises à jour sans avoir à les recapturer depuis le début.
• Documentez ce que chaque image montre. Un commentaire dans le MDX ou un manifeste d’images partagé indiquant quel contenu une image représente permet d’identifier plus rapidement les ressources obsolètes lors de la révision.

​

Questions fréquemment posées

Dois-je utiliser des captures d'écran ou du texte pour les instructions étape par étape ?

Préférez le texte avec des captures d’écran en complément, pas en remplacement. Le texte est plus rapide à parcourir, plus facile à rechercher et moins coûteux à mettre à jour. Ajoutez une capture d’écran lorsque les utilisateurs doivent identifier visuellement quelque chose dans l’interface ou lorsqu’un flux de travail serait véritablement confus sans le voir. Un schéma courant est de décrire l’étape en texte et d’inclure une capture d’écran uniquement pour les étapes où l’orientation visuelle est importante.

Comment gérer les captures d'écran lorsque l'interface est mise à jour ?

Le chemin le plus rapide est de recapturer les captures d’écran spécifiques qui ont changé plutôt que de tout mettre à jour d’un coup. Les captures d’écran étroitement recadrées qui se concentrent sur un seul élément changent moins fréquemment que les captures pleine page. Lorsqu’une refonte majeure de l’interface est déployée, traitez les mises à jour des captures d’écran comme un sprint de documentation avec un périmètre défini plutôt qu’une distraction permanente.

Quelle est la différence entre utiliser des GIFs et de courtes vidéos ?

Les GIFs se lisent en boucle automatiquement, ne nécessitent aucune interaction de l’utilisateur et s’intègrent directement dans la page sans lecteur. Ils fonctionnent bien pour les interactions simples et courtes où la boucle est utile. Les courtes vidéos sont préférables pour tout ce qui dure plus de quelques secondes, tout ce qui bénéficie de l’audio, ou tout flux de travail suffisamment complexe pour que les utilisateurs aient besoin de mettre en pause et de consulter des images spécifiques. Les vidéos offrent également un meilleur support d’accessibilité — les GIFs n’ont pas de contrôle de pause ni d’équivalent de texte alternatif au-delà d’une description dans le contenu environnant.

Ai-je besoin de texte alternatif si l'image est décorative ?

Si une image n’apporte aucune information — un séparateur purement décoratif ou un élément d’arrière-plan — utilisez un attribut alt vide (alt="") pour indiquer aux lecteurs d’écran de l’ignorer. Mais la plupart des images dans la documentation sont informatives, pas décoratives. En cas de doute, rédigez un texte alternatif.