Vidéos

Table des matières

Directives pour les vidéos

Les vidéos sont rarement utilisées dans la documentation de Docker. Lorsqu'elles sont utilisées, la vidéo doit compléter le texte écrit et ne pas être le seul format de documentation. Les vidéos peuvent prendre plus de temps à produire et être plus difficiles à maintenir que le texte écrit ou même les captures d'écran, alors considérez ce qui suit avant d'ajouter une vidéo :

Pouvez-vous démontrer un besoin client clair pour l'utilisation de la vidéo ?
La vidéo offre-t-elle un nouveau contenu, plutôt que de lire directement ou de réutiliser la documentation officielle ?
Si la vidéo contient des interfaces utilisateur susceptibles de changer régulièrement, avez-vous un plan de maintenance pour garder la vidéo à jour ?
Le ton et la voix de la vidéo sont-ils conformes au reste de la documentation ?
Avez-vous envisagé d'autres options, comme des captures d'écran ou la clarification de la documentation existante ?
La qualité de la vidéo est-elle similaire au reste de la documentation de Docker ?
La vidéo peut-elle être liée ou intégrée depuis le site ?

Si tous les critères ci-dessus sont remplis, vous pouvez vous référer aux meilleures pratiques suivantes avant de créer une vidéo à ajouter à la documentation Docker.

Meilleures pratiques

Déterminez le public de votre vidéo. La vidéo sera-t-elle un aperçu général pour les débutants, ou sera-t-elle une plongée en profondeur dans un processus technique conçu pour un utilisateur avancé ?
Les vidéos doivent durer moins de 5 minutes. Gardez à l'esprit la durée nécessaire de la vidéo pour expliquer correctement le sujet, et si la vidéo doit durer plus de 5 minutes, envisagez plutôt du texte, des diagrammes ou des captures d'écran. Ceux-ci sont plus faciles à parcourir pour un utilisateur à la recherche d'informations pertinentes.
Les vidéos doivent respecter les mêmes normes d'accessibilité que le reste de la documentation.
Assurez la qualité de votre vidéo en écrivant un script (s'il y a une narration), en vous assurant que plusieurs navigateurs et URL ne sont pas visibles, en floutant ou en recadrant toute information sensible, et en utilisant des transitions fluides entre les différents navigateurs ou écrans.

Les vidéos ne sont pas hébergées dans le dépôt de documentation Docker. Pour ajouter une vidéo, vous pouvez utiliser un lien vers du contenu hébergé, ou l'intégrer en utilisant un iframe.

iframe

Pour intégrer une vidéo sur une page de documentation, utilisez un élément <iframe> :

<iframe
  class="border-0 w-full aspect-video mb-8"
  allow="fullscreen"
  title=""
  src=""
  ></iframe>

asciinema

asciinema est un outil en ligne de commande pour enregistrer les sessions de terminal. Les enregistrements peuvent être intégrés sur le site de documentation. Ils sont similaires aux blocs de code console, mais comme ce sont des vidéos lisibles et déplaçables, ils ajoutent un autre niveau d'utilité par rapport aux blocs de code statiques dans certains cas. Le texte d'une "vidéo" asciinema peut également être copié, ce qui les rend plus utiles.

Envisagez d'utiliser un enregistrement asciinema si :

L'entrée/sortie des commandes du terminal est trop longue pour un exemple statique (vous pourriez également envisager de tronquer la sortie)
Les étapes que vous voulez montrer sont facilement démontrables en quelques commandes
Lorsqu'il est utile de voir à la fois les entrées et les sorties des commandes

Pour créer un enregistrement asciinema et l'ajouter à la documentation :

Installez le CLI asciinema
Exécutez asciinema auth pour configurer votre client et créer un compte
Démarrez un nouvel enregistrement avec asciinema rec
Exécutez les commandes de votre démo et arrêtez l'enregistrement avec <C-d> ou exit
Téléchargez l'enregistrement sur <asciinema.org>
Intégrez le lecteur avec une balise <script> en utilisant le bouton Partager sur <asciinema.org>