Verwenden von Videos in GitHub-Dokumentationen

Informationen zu Videos in GitHub Docs

Videos werden in GitHub Docs selten verwendet. Wenn Videos notwendig sind, um einen Artikel für die Benutzer*innen optimal zu gestalten, werden sie zusammen mit geschriebenem Text verwendet. Videos sind kein Ersatz für geschriebene Inhalte. Videos sollten nie das einzige Mittel sein, um Informationen zu vermitteln, da sie schwieriger auf dem neuesten Stand zu halten und nicht für alle zugänglich sind.

Verwende diese Richtlinien, um festzustellen, ob ein Video in einen Artikel oder auf einer Angebotsseite in die Dokumentation aufgenommen werden kann.

Wenn du einem Video einen Link hinzufügen oder ein Video in GitHub Docs einbetten möchtest, füge die Metadaten des Videos in der Datei Videos in GitHub Docs im github/docs-Repository hinzu.

Das Dokumentationsteam erstellt oder verwaltet keine Videoinhalte. Videos sind lediglich eine Ergänzung, um wichtige oder komplexe Themen zu vermitteln, und sollten sparsam eingesetzt werden, da sie keine eigener Inhaltstyp des Dokumentationsteams sind.

Checkliste für Videos

Mit dieser Checkliste können Sie schnell feststellen, ob ein Video für einen Artikel oder eine Landing Page geeignet ist.

• Ist das Video die einzige Möglichkeit, die Informationen zu vermitteln?
• Besitzt GitHub das Video?
• Ist das Video gut produziert? (Weitere Informationen findest du im Abschnitt Best Practices.)
• Ist das Video für eine möglichst große Gruppe von Benutzer*innen zugänglich? (Weitere Informationen findest du im Abschnitt Barrierefreiheitsanforderungen.)
• Ist das Video weniger als fünf Minuten lang?
• Hat das Video eine bestimmte Zielgruppe und einen bestimmten Zweck in der Dokumentation? Wenn es nur für ein bestimmtes Produkt oder eine bestimmte Funktion relevant ist, muss es versioniert werden. Weitere Informationen findest du im Abschnitt Versionsverwaltung.

Wenn Sie einen dieser Punkte mit „Nein“ beantworten, ist das Video nicht dazu geeignet, zur GitHub Docs hinzugefügt zu werden.

Verwalten von Videos

Wenn es für ein Video einen Wartungsplan oder ein Team gibt, das direkt für die Überprüfung und das Aktualisieren des Inhalts zuständig ist, wenn dieser veraltet ist, können Sie das Video ohne weitere Schritte aufnehmen.

Wenn es für das Video keinen Wartungsplan gibt, erstelle ein Issue mit einem entsprechenden Zieldatum, um das Video zu überprüfen oder zu entfernen.

Bewährte Methoden

Mit diesen Best Practices können Sie feststellen, ob ein Video gut produziert wurde und von ausreichender Qualität ist, um in die GitHub Docs aufgenommen zu werden.

In guten Videos wird ein Lehrplan eingeführt, der Schritte und Ziele enthält, sodass die Zuschauer*innen schnell erfahren, was sie lernen werden. Die Videos sind anschaulich und zeigen und erklären die jeweiligen Schritte, die durchgeführt werden. Videos sollten ansprechend und ermutigend sein. Die Videos müssen gut produziert sein, um in die GitHub Docs aufgenommen zu werden. Ein gut produziertes Video enthält nur wenige Barrieren für Menschen mit Behinderungen, ist professionell gesprochen (falls es sich um ein Video mit Audiokommentar handelt), hat klare visuelle Elemente und stammt aus einer vertrauenswürdigen Quelle wie GitHub oder Microsoft.

Videos sind in drei Kategorien unterteilt: Produktübersichten, Featurevideos und Tutorials. Diese Beschreibungen sind Verallgemeinerungen der einzelnen Videotypen. Einige Videos lassen sich vielleicht nicht genau in eine Kategorie einordnen, können aber dennoch nützlich sein, ohne die genauen Richtlinien zu erfüllen.

Produktübersichten

• Zweck: Es soll kurz erläutert werden, was das Produkt ist, was die wichtigsten Funktionen sind, und das Interesse der Leute soll geweckt werden.
• Länge: Weniger als eine Minute
• Mögliche Zielgruppen: Personen, die wissen möchten, ob ein Feature für ihre Zwecke nützlich ist, Personen, die neu bei GitHub sind und versuchen zu verstehen, was die Produkte tun
• Mögliche Stellen in der Dokumentation: Landing Pages und Leitfäden

Featurevideos

• Zweck: Ergänzung konzeptioneller oder verfahrensbezogener Inhalte
• Länge: So kurz wie möglich, aber nicht länger als fünf Minuten. Längere Inhalte sollten in mehrere kürzere, fokussierte Videos aufgeteilt werden.
• Mögliche Zielgruppen: Personen, die etwas über oder die Verwendung eines Features lernen möchten
• Mögliche Stellen in der Dokumentation: Leitfäden, konzeptionelle Artikel und verfahrensbezogene Artikel

Lernprogramme

• Zweck: Anfänger*innen soll der Einstieg in ein Produkt erleichtert werden, die Annahme des Produkts soll gefördert werden, und es sollen komplexe Funktionen erläutert werden.
• Länge: Einzelne Videos sollten maximal fünf Minuten lang sein. Bei komplexen Themen kann eine Reihe von kürzeren Videos über einen Artikel verteilt werden. Die Gesamtlänge sollte maximal 15 Minuten betragen.
• Mögliche Zielgruppen: Neue Benutzer*innen von Features oder Produkten
• Mögliche Stellen: Leitfäden

Wann Videos verwendet werden sollten

Wir können Videos anstelle anderer Visuals wie Screenshots oder Diagramme verwenden, wenn es wichtig ist, Bewegungen oder Zustandsänderungen anzuzeigen, z. B. wenn eine Person von einem Bildschirm zu einem anderen navigiert oder ein Feature vorgibt, bei dem mehrere Menüs durchlaufen werden. Screenshots oder Text können jedoch ausreichen, um diese Prozeduren zu erläutern.

Videos können auch hilfreich sein, um Funktionen oder Produkte vorzustellen, wobei ein 30 Sekunden langes Video Informationen ergänzen kann, für die mehrere Absätze erforderlich wären.

Verwende Videos, die den Wert der gezeigten Prozedur oder des Konzepts erklären.

Wann keine Videos verwendet werden sollten

Verwende keine Videos für Funktionen, die schnell geändert werden und dazu führen können, dass die Videos nicht mehr aktuell sind. Verwende keine Videos, die dem schriftlichen Inhalt oder irgendwelchen Bestandteilen von Styleguide widersprechen. Verwende keine Videos, die nur eine Aufgabe zeigen, ohne das die Prozedur erklärt oder erläutert wird. Videos müssen nützlich und relevant sein, was bedeutet, dass sie auch im Laufe der Zeit korrekt bleiben müssen.

Anforderungen an Barrierefreiheit

Dies sind die Mindestanforderungen für ein Video, das in die GitHub Docs aufgenommen werden soll. Wenn ein Video gegen eine dieser Anforderungen verstößt, kann es nicht der Dokumentation hinzugefügt werden.

• Es darf keine Blink- oder Stroboskopeffekte geben.
• Das Video muss geschlossene Untertitel aufweisen. Weitere Informationen findest du unter Erstellen von Videountertiteln.
• Die Grafiken und die Untertitel dürfen sich nicht überlappen.
• Die Typografie muss gut lesbar sein.
• Alle Überlagerungen müssen ein ausreichendes Kontrastverhältnis aufweisen.
• Jeder Text muss lange genug auf dem Bildschirm zu sehen sein, um gelesen werden zu können (der Text sollte länger auf dem Bildschirm erscheinen, als es dauert, ihn zweimal laut vorzulesen).
• Es müssen korrekturgelesene, beschreibende Transkripte für die einzelnen Szenen vorliegen. Weitere Informationen findest du weiter unten unter Erstellen von Videotranskripten.
• Videos werden nicht automatisch wiedergegeben.

Erstellen von Videountertiteln

Die Videos müssen mit von Menschen erstellten Untertiteln versehen sein, bevor sie auf der Dokumentationswebsite veröffentlicht werden. Du kannst die automatische Untertitelung nutzen, um die Untertitel zu erstellen, aber sie müssen von einer Person Korrektur gelesen und auf ihre Richtigkeit überprüft werden. Wenn der Videohostingdienst über ein eigenes Untertitel-Tool verfügt, wie z. B. YouTube, können Sie dieses Tool verwenden, um Untertitel vorzubereiten oder eine ordnungsgemäß formatierte SRT- oder VTT-Transkriptdatei zu erstellen, die zusammen mit dem Video hochgeladen wird.

Das Erstellen von Untertiteln ist Teil des Produktionsprozesses von Videos, die für mehr Personen zugänglich sind. Daher sollte derdie Urheberin eines Videos, das zu GitHub Docs hinzugefügt wird, Untertitel bereitstellen.

Richtlinien für Untertitel

Die Untertitel sollten nach Möglichkeit genau mit den im Video gesprochenen Worten übereinstimmen. Paraphrasiere oder kürze die Untertitel nicht, es sei denn, es ist aus Zeitgründen schwierig, die Untertitel in der vorgegebenen Zeit zu lesen.

Die Untertitel müssen so synchronisiert werden, dass sie ungefähr zur gleichen Zeit wie der Ton erscheinen. Die Untertitel sollten immer dann auf dem Bildschirm erscheinen, wenn derdie Sprecherin zu sprechen beginnt. Bei schnellen Redebeiträgen, bei denen es schwierig wäre, die Untertitel zeitlich genau auf den Ton abzustimmen, können Sie die Untertitel so verlängern, dass sie nach dem Ende des Redebeitrags auf dem Bildschirm bleiben.

Wenn ein Video mehrere Sprecherinnen hat, gib die Sprecherinnen in den Untertiteln an. Füge vor dem Satzanfang den Namen des Sprechers bzw. der Sprecherin oder einen beschreibenden Namen wie Developer ein. Beispiel: Jimmy: Hello.. Du musst dies nur tun, wenn der Sprecher wechselt, also nicht bei jeder Textzeile. Wenn aus dem Bildmaterial ersichtlich ist, wer spricht, müssen Sie dendie Sprecherin nicht nennen.

Die Untertitel müssen ein- oder zweizeilig sein und dürfen nicht mehr als 32 Zeichen pro Zeile enthalten. Setze jeden neuen Satz in eine neue Zeile. Wenn Sie eine Zeile mitten im Satz umbrechen müssen, sollten Sie das an einem logischen Punkt tun, zum Beispiel nach Kommas oder vor Konjunktionen wie and oder but.

Hinzufügen und Bearbeiten von Untertiteln auf YouTube

Informationen zu Videos, die auf YouTube gehostet werden, findest du unter Hinzufügen von Untertiteln und Beschriftungen und Bearbeiten oder Entfernen von Untertiteln in der YouTube-Dokumentation.

Erstellen von Videotranskripten

Für jedes Video, das in den Dokumenten verlinkt oder eingebettet ist, muss ein beschreibendes Transkript des Videos vorliegen. Transkriptartikel sind wie andere Artikel mit YAML-Frontmatter und Markdowninhalten formatiert. Um der Dokumentationswebsite ein Transkript hinzuzufügen, erstelle einen Artikel in content/video-transcripts, und füge das Transkript in den Text des Artikels ein. Gib dem Artikel einen Dateinamen wie transcript-VIDEO-NAME.md und eine title-Frontmattereigenschaft von Transcript - VIDEO NAME. Füge den Artikel der index.md-Datei im video-transcripts-Verzeichnis hinzu.

Verwende keine Liquid-Variablen oder wiederverwendbare Variablen, um beispielsweise Produktnamen im Transkript zu ersetzen. Das Transkript sollte dem Audiomaterial des Videos entsprechen, und wir sollten keinen Text im Transkript ändern, wenn wir eine Variable oder ein wiederverwendbares Element nach der Produktion des Videos aktualisieren.

Das Erstellen von Transkripts ist Teil des Produktionsprozesses von Videos, die für mehr Personen zugänglich sind. Daher sollte derdie Urheberin eines Videos, das zu der Dokumentationswebsite hinzugefügt wird, den Inhalt für ein Transkript bereitstellen.

Du kannst Untertitel als Grundlage für ein Transkript verwenden. Bearbeite die Untertitel, um alle Zeitstempel zu entfernen, und füge die unten aufgeführten relevanten Informationen ein. Ein beschreibendes Transkript enthält eine Textversion sowohl der Audio- als auch der visuellen Informationen, die zum Verständnis des Inhalts eines Videos erforderlich sind.

• Wenn ein Video mehrere Sprecherinnen hat, gib die Sprecherinnen im Transkript an.
• Wenn das Geschlecht eines Sprechers bekannt ist, können Sie dessen bevorzugte Pronomen verwenden, wenn Sie seine Handlungen beschreiben. Wenn z. B She points to the computer screen. das Geschlecht des Sprechers für das beschriebene visuelle Objekt unbekannt oder irrelevant ist, können Sie das Pronomen „sie“ im Singular verwenden.
• Formatiere das Transkript in logischen Absätzen, Listen und Abschnitten. Wenn es zum besseren Verständnis des Inhalts beiträgt, können Sie den Abschnitten Überschriften hinzufügen. Überlege, wie eine Person Informationen aus dem Transkript erhält, wenn sie sich nicht auch das Video ansieht.
• Füge jeglichen Text auf dem Bildschirm, relevante visuelle Elemente oder nichtsprachliche Klänge hinzu, die nicht in den Untertiteln enthalten sind. Platziere diese Beschreibungen nach dem gesprochenen Text, der im Video zu hören ist. Formatiere visuelle Informationen in Klammern. Beispiel: [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.].
• Füge der YAML-Frontmatter des Transkriptartikels eine product_video-Eigenschaft hinzu. Der Wert der product_video-Eigenschaft ist die YouTube-URL des Videos. Die YouTube-URL des Videos wird als externer Link im Transkriptartikel angezeigt.
• Gib am Ende des Transkripts End of transcript. ein, und verlinke die Landing Page für das Produkt, um das es im Video geht, mit dem Muster For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Weitere Beispiele für Audio- und visuelle Transkription findest du in der W3C-Dokumentation unter Texttranskript mit Beschreibung des Bildmaterials.

Verknüpfen mit Transkripten aus extern gehosteten Videos

Füge einen Link zum Artikel mit dem Transkript eines Videos in der Beschreibung des Videos auf der Plattform hinzu, auf der es gehostet wird. Weitere Informationen findest du unter Bearbeiten von Videoeinstellungen in der YouTube-Dokumentation.

Verknüpfen mit Transkripten für eingebettete Videos

Füge in jedem Inhalt mit einem eingebetteten Video eine product_video_transcript-Eigenschaft unterhalb der product_video-Eigenschaft in der YAML-Frontmatter hinzu. Der Wert von product_video_transcript ist ein Link zum Transkriptartikel im video-transcripts-Verzeichnis.

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

Titel für Videos

Titel sollten beschreibend sein und den Richtlinien für Titel im Inhaltsmodell entsprechen. Weitere Informationen finden Sie unter Inhalt eines GitHub-Docs-Artikels.

Versionsverwaltung

Wenn ein Video nur für bestimmte GitHub-Produkte relevant ist (Free, Pro und Team; GitHub Enterprise Server und GitHub Enterprise Cloud), muss das Video für diese Produkte versioniert sein. Verwende bedingte Liquid-Anweisungen, um die Videos entsprechend zu versionieren. Die bedingte Versionierung von Liquid muss möglicherweise bei der erstmaligen Erstellung des Inhalts hinzugefügt werden, oder sie muss hinzugefügt werden, wenn der Inhalt für ein Featureupdate oder GitHub Enterprise-Release aktualisiert wird. Weitere Informationen zu flüssigen bedingten Anweisungen und Versionsverwaltung findest du unter Dokumentation zur Versionierung.

Videohosting

Videos müssen an einem Ort gehostet werden, der GitHub gehört und auf den das Dokumentationsteam Zugriff hat. Videos sollten keine Benutzer nachverfolgen oder Cookies verwenden. Derzeit werden die Videos von GitHub auf YouTube gehostet und den Dokumenten mithilfe des erweiterten Datenschutzmodus hinzugefügt, indem die Domain für die eingebettete URL von https://www.youtube.com/VIDEO auf https://www.youtube-nocookie.com/VIDEO geändert wird.