Utilisation de vidéos dans GitHub Docs

Ce guide explique comment créer des vidéos qui répondent aux besoins des utilisateurs de GitHub Docs.

Dans cet article

À propos des vidéos dans GitHub Docs

Les vidéos sont rarement utilisées dans GitHub Docs. Quand des vidéos sont nécessaires pour offrir la meilleure expérience utilisateur pour un article, elles sont utilisées avec du texte écrit. Les vidéos ne remplacent pas le contenu écrit. Les vidéos ne doivent jamais être le seul moyen de communiquer des informations, car elles sont plus difficiles à tenir à jour et ne sont pas accessibles à tout le monde.

Suivez ces recommandations pour déterminer s'il est approprié d'inclure une vidéo dans un article ou sur une page de destination dans la documentation.

Si vous ajoutez un lien vers une vidéo ou si vous incorporez une vidéo dans GitHub Docs, ajoutez les métadonnées de la vidéo au fichier Vidéos dans GitHub Docs », dans le référentiel github/docs.

L'équipe Docs n'effectue aucune opération liée à la création ou la gestion du contenu vidéo. Les vidéos sont uniquement conçues comme un complément visant à faciliter la communication de sujets importants ou complexes. Il convient de les utiliser avec modération, car elles ne font pas partie du type de contenu appartenant à l'équipe Docs.

Check-list relative aux vidéos

Utilisez cette check-list pour déterminer rapidement s'il convient d'ajouter une vidéo à un article ou une page de destination.

  • La vidéo est-elle le seul moyen de communiquer les informations ?
  • Est-ce que GitHub est propriétaire de la vidéo ?
  • La vidéo est-elle produite correctement ? (Pour plus d’informations, consultez la section Bonnes pratiques.)
  • La vidéo est-elle accessible au groupe d'utilisateurs le plus large possible ? (Pour plus d’informations, consultez la section Exigences d’accessibilité.)
  • La vidéo dure-t-elle moins de cinq minutes ?
  • La vidéo a-t-elle une audience et un objectif spécifiques dans la documentation ? Si elle concerne uniquement un produit ou une fonctionnalité spécifique, vous devez la versionner. Pour plus d’informations, consultez la section Contrôle de version.

Si vous répondez « non » à l'un de ces points, cela signifie que la vidéo ne peut pas être ajoutée à GitHub Docs.

Maintenance des vidéos

Si une vidéo est soumise à une planification de maintenance ou est gérée par une équipe responsable de l'audit et de la mise à jour du contenu en cas d'obsolescence, vous pouvez l'inclure sans aucune étape supplémentaire.

Si la vidéo n'a pas de planification de maintenance, créez un problème avec une date cible appropriée pour passer en revue ou supprimer la vidéo.

Meilleures pratiques

Suivez ces bonnes pratiques pour déterminer si une vidéo est bien produite et si elle est d'une qualité suffisante pour être incluse dans GitHub Docs.

Les bonnes vidéos présentent un programme pédagogique qui comprend des étapes et des objectifs pour que le spectateur sache rapidement ce qu'il va apprendre. Les vidéos sont démonstratives, car elles montrent et expliquent les étapes appropriées qui sont effectuées. Les vidéos doivent être engageantes et encourageantes. Les vidéos doivent être produites correctement pour être incluses ensuite dans GitHub Docs. Une vidéo bien produite comporte peu d'obstacles pour les personnes handicapées, dispose d'une narration professionnelle (si la vidéo est commentée), de visuels clairs, et provient d'une source approuvée telle que GitHub ou Microsoft.

Les vidéos sont généralement regroupées en trois catégories : les vues d'ensemble des produits, les vidéos de fonctionnalités et les tutoriels. Ces descriptions sont des généralisations de chaque type de vidéo. Il arrive que certaines vidéos ne s'intègrent pas parfaitement dans une seule catégorie. Toutefois, elles peuvent être utiles même si elles ne répondent pas exactement aux recommandations.

Vues d'ensemble des produits

  • Objectif : Expliquez brièvement ce qu'est le produit, présentez ses fonctionnalités principales, et suscitez l'intérêt des utilisateurs
  • Durée : Moins d'une minute
  • Audiences possibles : Personnes qui souhaitent savoir si une fonctionnalité est utile pour atteindre leurs objectifs, personnes qui découvrent GitHub et qui tentent de comprendre à quoi servent les produits
  • Emplacements possibles dans la documentation : Pages de destination et guides

Vidéos des fonctionnalités

  • Objectif : Compléter le contenu conceptuel ou procédural
  • Durée : Aussi courte que possible, sans dépasser cinq minutes. Divisez un contenu long en plusieurs vidéos plus courtes et ciblées
  • Audiences possibles : Personnes qui découvrent une fonctionnalité ou apprennent à l'utiliser
  • Emplacements possibles dans la documentation : Guides, articles conceptuels, articles relatifs aux procédures

Tutoriels

  • Objectif : Aider les utilisateurs novices à utiliser un produit, à en favoriser l'adoption ou à expliquer des fonctionnalités complexes
  • Durée : Les vidéos individuelles doivent durer cinq minutes au maximum. Les sujets complexes peuvent comporter une série de vidéos plus courtes réparties sur un article. La durée totale doit être de 15 minutes au maximum
  • Audiences possibles : Nouveaux utilisateurs de fonctionnalités ou de produits
  • Emplacements possibles : Guides

Quand utiliser des vidéos

Nous pouvons utiliser des vidéos à la place d'autres visuels tels que des captures d'écran ou des diagrammes quand il est important de montrer un mouvement ou des changements d'état, par exemple quand une personne navigue d'un écran à un autre ou fait la démonstration d'une fonctionnalité qui implique une progression dans plusieurs menus. Toutefois, des captures d'écran ou du texte peuvent suffire à expliquer ces procédures.

Les vidéos peuvent également être utiles pour présenter des fonctionnalités ou des produits. Une vidéo de 30 secondes peut compléter des informations nécessitant la rédaction de plusieurs paragraphes.

Utilisez des vidéos qui expliquent la valeur de la procédure ou du concept qu'elles illustrent.

Quand ne pas utiliser des vidéos

N'utilisez pas de vidéos pour les fonctionnalités qui changent rapidement et qui risquent de rendre les vidéos obsolètes. N’utilisez pas de vidéos qui contredisent le contenu écrit, ou qui enfreignent une partie de Guide de style. N'utilisez pas de vidéos qui montrent simplement une tâche sans expliquer ou détailler la procédure. Les vidéos doivent être utiles et pertinentes, ce qui signifie qu'elles doivent rester précises au fil du temps.

Exigences d'accessibilité

Il s'agit des conditions minimales pour qu'une vidéo soit incluse dans GitHub Docs. Si une vidéo ne respecte pas l'un de ces impératifs, elle ne peut pas être ajoutée à la documentation.

  • Aucun effet de clignotement ou effet stroboscopique
  • Sous-titres codés obligatoires. Pour plus d’informations, consultez Création de sous-titres vidéo ci-dessous
  • Aucun graphisme ne doit chevaucher l'emplacement d'affichage des sous-titres
  • La typographie doit être lisible
  • Les superpositions doivent avoir des rapports de contraste suffisants
  • Le texte doit rester à l'écran suffisamment longtemps pour pouvoir être lu (le texte doit apparaître à l'écran plus longtemps qu'il n'en faut pour le lire à voix haute deux fois)
  • Vous devez avoir relu les transcriptions descriptives de ce qui se passe scène par scène. Pour plus d’informations, consultez Création de transcriptions vidéo ci-dessous
  • Les vidéos ne sont pas lues automatiquement

Création de sous-titres vidéo

Les vidéos doivent comporter des sous-titres générés manuellement avant d'être ajoutées au site Docs. Vous pouvez utiliser la technologie relative aux sous-titres automatiques pour créer les sous-titres. Toutefois, ceux-ci doivent être relus et modifiés par une personne chargée de garantir leur justesse. Si le service d'hébergement vidéo dispose d'un outil de sous-titrage natif, par exemple YouTube, vous pouvez l'utiliser pour préparer des sous-titres ou créer un fichier de transcription SRT ou VTT au format approprié, à charger avec la vidéo.

La création de sous-titres fait partie du processus de production de vidéos accessibles à un plus grand nombre de personnes. Le propriétaire d'une vidéo ajoutée à GitHub Docs doit donc fournir des sous-titres.

Recommandations relatives aux sous-titres

Dans la mesure du possible, les sous-titres doivent correspondre exactement aux mots prononcés dans la vidéo. Ne paraphrasez pas et ne tronquez pas les sous-titres, sauf si des contraintes de temps importantes empêchent une personne de lire correctement les sous-titres dans le délai imparti.

Les sous-titres doivent être synchronisés pour apparaître à peu près en même temps que le contenu audio. Les sous-titres doivent toujours être programmés pour apparaître à l'écran au moment où l'orateur commence à parler. Quand le débit vocal est rapide, et qu'il est difficile de lire les sous-titres synchronisés avec précision par rapport au contenu audio, vous pouvez étendre la durée d'affichage des sous-titres pour qu'ils restent à l'écran plus longtemps.

Si une vidéo comporte plusieurs orateurs, identifiez-les dans les sous-titres. Pour ce faire, ajoutez le nom de l'orateur, ou un nom descriptif tel que Developer, avant le début de la phrase. Par exemple : Jimmy: Hello.. Vous n'avez besoin de le faire qu'au moment où l'orateur change, pas pour chaque ligne de dialogue. Si les visuels montrent clairement qui est en train de parler, vous n'avez pas besoin d'identifier l'orateur.

Les sous-titres doivent comporter une ou deux lignes, sans dépasser 32 caractères par ligne. Placez chaque nouvelle phrase sur une nouvelle ligne. Si vous devez arrêter une ligne au milieu d'une phrase, faites-le à un emplacement logique, par exemple après des virgules ou avant des conjonctions telles que and ou but.

Ajout et modification de sous-titres sur YouTube

Pour les vidéos hébergées sur YouTube, consultez Ajouter des sous-titres et Modifier ou supprimer des sous-titres dans la documentation YouTube.

Création de transcriptions vidéo

Pour chaque vidéo liée ou incorporée dans la documentation, nous devons disposer d'une transcription descriptive de la vidéo. Les articles de transcription sont mis en forme comme les autres articles, avec des informations préliminaires YAML et du contenu Markdown. Pour ajouter une transcription au site Docs, créez un article dans content/video-transcripts, puis incluez la transcription en tant que corps de texte de l'article. Attribuez à l'article un nom de fichier, par exemple transcript-VIDEO-NAME.md, et affectez à la propriété d'informations préliminaires title la valeur Transcript - VIDEO NAME. Ajoutez l'article au fichier index.md dans le répertoire video-transcripts.

N'utilisez pas de variables Liquid ou d'éléments réutilisables pour remplacer des éléments tels que des noms de produits dans la transcription. La transcription doit être fidèle au contenu audio de la vidéo. Nous ne devons pas changer le texte de la transcription à la suite de la mise à jour d'une variable ou d'un élément réutilisable après la production de la vidéo.

La création de transcriptions fait partie du processus de production de vidéos accessibles à un plus grand nombre de personnes. Le propriétaire d'une vidéo ajoutée au site Docs doit donc fournir le contenu d'une transcription.

Vous pouvez utiliser les sous-titres en tant que base d'une transcription. Modifiez les sous-titres pour supprimer tous les horodatages, et incluez les informations appropriées qui sont détaillées ci-dessous. Une transcription descriptive comprend une version texte des informations audio et visuelles nécessaires à la compréhension du contenu d'une vidéo.

  • Si une vidéo comporte plusieurs orateurs, identifiez-les dans la transcription.
  • Si le sexe d’un orateur est connu, vous pouvez utiliser leurs pronoms préférés lors de la description de leurs actions. Par exemple, She points to the computer screen. Si le sexe de l’orateur est inconnu ou non pertinent pour le visuel décrit, vous pouvez utiliser le singulier qu’il pronoun.
  • Mettez en forme la transcription à l'aide de paragraphes, de listes et de sections logiques. Si cela permet aux utilisateurs de mieux comprendre le contenu, vous pouvez ajouter des titres aux sections. Réfléchissez à la façon dont une personne peut interpréter les informations de la transcription si elle ne visionne pas également la vidéo.
  • Ajoutez le texte à l'écran, les visuels pertinents ou les sons non vocaux qui ne sont pas inclus dans les sous-titres. Placez ces descriptions après le texte parlé qui les accompagne dans la vidéo. Mettez en forme les informations visuelles entre parenthèses. Par exemple : [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.].
  • Ajoutez une propriété product_video aux informations préliminaires YAML de l'article de transcription. La valeur de la propriété product_video correspond à l'URL YouTube de la vidéo. L'URL YouTube de la vidéo s'affiche sous forme de lien externe dans l'article de transcription.
  • À la fin de la transcription, écrivez End of transcript. et créez un lien vers la page de destination du produit décrit dans la vidéo à l'aide du modèle For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Pour plus d’exemples de transcriptions audio et visuelles, consultez Transcription de texte avec description des visuels dans la documentation du W3C.

Liaison vers des transcriptions de vidéos hébergées de manière externe

Ajoutez un lien vers l'article avec la transcription d'une vidéo dans la description de la vidéo sur la plateforme où elle est hébergée. Pour plus d’informations, consultez Modifier les paramètres vidéo dans la documentation YouTube.

Liaisons vers des transcriptions pour les vidéos incorporées

Dans un contenu avec une vidéo incorporée, ajoutez une propriété product_video_transcript sous la propriété product_video au sein des informations préliminaires YAML. La valeur de product_video_transcript est un lien vers l'article de transcription dans le répertoire video-transcripts.

title: Example product landing page
product_video: 'https://www.youtube-nocookie.com/embed/URL'
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE

Titres des vidéos

Les titres doivent être descriptifs et suivre les recommandations relatives aux titres figurant dans le modèle de contenu. Pour plus d’informations, consultez « Contenu d'un article GitHub Docs ».

Contrôle de version

Si une vidéo n'est pertinente que pour des produits GitHub spécifiques (Free, Pro et Team, GitHub Enterprise Server, et GitHub Enterprise Cloud), celle-ci doit être versionnée pour ces produits. Utilisez les instructions conditionnelles Liquid pour versionner les vidéos de manière appropriée. Vous devrez peut-être ajouter un versioning basé sur des instructions conditionnelles Liquid au moment de la création du contenu, ou quand le contenu fera l'objet d'une mise à jour des fonctionnalités ou d'une mise à jour de version liée à GitHub Enterprise. Pour plus d'informations sur les instructions conditionnelles Liquid et le contrôle de version, consultez Documentation sur le contrôle de version.

Hébergement vidéo

Les vidéos doivent être hébergées à un emplacement appartenant à GitHub, et auquel l'équipe Docs a accès. Les vidéos ne doivent pas effectuer un suivi des utilisateurs ni utiliser de cookies. Pour le moment, les vidéos de GitHub sont hébergées sur YouTube et ajoutées à la documentation à l'aide du mode de confidentialité amélioré en changeant le domaine de l'URL incorporée de https://www.youtube.com/VIDEO en https://www.youtube-nocookie.com/VIDEO.