Como usar vídeos no GitHub Docs

Sobre os vídeos do GitHub Docs

Os vídeos raramente são usados no GitHub Docs. Quando os vídeos são necessários para fornecer a melhor experiência do usuário para um artigo, eles são usados acompanhados de um texto escrito. Os vídeos não substituem o conteúdo escrito. Eles nunca devem ser a única maneira como as informações são comunicadas porque são mais difíceis de ser mantidos atualizados e não são acessíveis a todos.

Use essas diretrizes para determinar se um vídeo é apropriado para ser incluído em um artigo ou em uma página de aterrissagem na documentação.

Se você adicionar um link a um vídeo ou inserir um vídeo no GitHub Docs, adicione os metadados do vídeo ao arquivo "Vídeos do GitHub Docs" no repositório github/docs.

A equipe do Docs não cria nem mantém o conteúdo do vídeo. Os vídeos são puramente complementares para ajudar a comunicar tópicos significativos ou complexos e devem ser usados com moderação porque não são um tipo de conteúdo pertencente à equipe do Docs.

Lista de verificação de vídeos

Use essa lista de verificação para determinar rapidamente se pode ser apropriado adicionar um vídeo a um artigo ou a uma página de aterrissagem.

O vídeo é a única maneira de comunicar as informações?
O GitHub é o proprietário do vídeo?
O vídeo foi bem produzido? (Confira a seção "Melhores práticas" para obter mais informações).
O vídeo é acessível para o grupo mais amplo possível de usuários? (Confira a seção "Requisitos de acessibilidade" para obter mais informações).
O vídeo tem menos de cinco minutos?
O vídeo tem um público-alvo e uma finalidade específicos na documentação? Se ele só for relevante a um produto ou a um recurso específico, você precisará fazer o controle da versão dele. Confira a seção "Controle de versão" para obter mais informações.

Se você responder "Não" a um desses itens, o vídeo não será adequado para adicionar ao GitHub Docs.

Como fazer a manutenção dos vídeos

Se um vídeo tiver um agendamento de manutenção ou uma equipe diretamente responsável por auditar e atualizar o conteúdo caso ele fique desatualizado, você poderá incluir o vídeo sem etapas adicionais.

Se o vídeo não tiver um agendamento de manutenção, crie um problema com uma data de destino apropriada para revisar ou remover o vídeo.

Práticas recomendadas

Use estas melhores práticas para ajudar a determinar se um vídeo foi bem produzido e se é de uma qualidade alta o suficiente para ser incluído no GitHub Docs.

Bons vídeos apresentam uma agenda instrucional que inclui etapas e metas para que alguém que esteja assistindo a ele saiba rapidamente o que aprenderá. Os vídeos são demonstrativos, mostrando e explicando as etapas relevantes que serão executadas. Eles devem ser interessantes e animadores. Precisam ser bem produzidos para serem incluídos no GitHub Docs. Um vídeo bem produzido contém poucos obstáculos para pessoas com deficiência, tem uma narração profissional (caso o vídeo seja narrado), tem elementos visuais claros e vem de uma fonte confiável, como o GitHub ou a Microsoft.

Os vídeos são amplamente agrupados em três categorias: visões gerais de produtos, vídeos de recursos e tutoriais. Essas descrições são generalizações de cada tipo de vídeo. Alguns vídeos talvez não se enquadrem perfeitamente em uma categoria, mas ainda podem ser úteis sem atender às diretrizes exatas.

Visões gerais de produtos

Finalidade: explicar brevemente o que é o produto, mostrar a funcionalidade principal e fazer com que as pessoas tenham interesse
Duração: menos de um minuto
Possíveis públicos-alvo: pessoas que desejam saber se um recurso é útil para as respectivas metas e pessoas que estão conhecendo o GitHub agora e tentando entender o que os produtos fazem
Possíveis locais na documentação: páginas de aterrissagem e guias

Vídeos de recursos

Finalidade: complementar o conteúdo conceitual ou de procedimentos
Duração: o mais curto possível, sem exceder cinco minutos. Divida um conteúdo mais longo em vários vídeos mais curtos e concentrados
Possíveis públicos-alvo: pessoas que estão aprendendo mais sobre um recurso ou como usá-lo
Possíveis locais na documentação: guias, artigos conceituais e artigos de procedimentos

Tutoriais

Finalidade: ajudar os usuários iniciantes a usar um produto, promover a adoção ou explicar funcionalidades complexas
Duração: os vídeos individuais devem ter cinco minutos ou menos. Os tópicos complexos podem ter uma série de vídeos mais curtos distribuídos por um artigo. O tamanho total deve ser de, no máximo, 15 minutos
Possíveis públicos-alvo: novos usuários de recursos ou produtos
Possíveis locais: guias

Quando usar vídeos

Podemos usar vídeos em vez de outros visuais, como capturas de tela ou diagramas, quando é importante mostrar movimentos ou alterações no estado, como quando alguém navega de uma tela para outra ou demonstra um recurso que envolve o progresso por meio de vários menus. No entanto, capturas de tela ou texto podem ser suficientes para explicar esses procedimentos.

Os vídeos também podem ser úteis para introduzir recursos ou produtos em que um vídeo de 30 segundos pode complementar informações que exigem a escrita de vários parágrafos.

Use vídeos que explicam o valor do procedimento ou do conceito que eles estão mostrando.

Quando não usar vídeos

Não use vídeos para recursos que mudam rapidamente e que podem tornar os vídeos desatualizados. Não use vídeos que contradizem o conteúdo escrito ou violem qualquer parte do "Guia de estilo". Não use vídeos que apenas mostrem uma tarefa sem explicar ou descrever em detalhes o procedimento. Os vídeos precisam ser úteis e relevantes, o que inclui manter-se preciso ao longo do tempo.

Requisitos de acessibilidade

Estes são os requisitos mínimos para que um vídeo seja incluído no GitHub Docs. Se um vídeo violar um desses requisitos, ele não poderá ser adicionado à documentação.

Sem efeitos de luzes piscantes ou estroboscópicos
Precisa ter legenda oculta. Confira "Como criar legendas de vídeo" abaixo para obter mais informações
Sem elementos gráficos sobrepostos no local em que as legendas aparecem
A tipografia precisa ser legível
Qualquer sobreposição precisa ter uma proporção de contraste suficiente
Qualquer texto precisa estar na tela tempo suficiente para ser lido (o texto deve aparecer na tela por mais tempo do que é necessário para lê-lo em voz alta duas vezes)
Precisa ter transcrições descritivas revisadas para o que acontece cena a cena. Confira "Como criar transcrições de vídeo" abaixo para obter mais informações
Os vídeos não são reproduzidos automaticamente

Como criar legendas de vídeo

Os vídeos precisam ter legendas geradas por humanos antes de serem adicionados ao site do Docs. Você pode usar a tecnologia de legenda automática para ajudar a criar as legendas, mas a precisão delas precisa ser revisada e editada por uma pessoa. Se o serviço de hospedagem de vídeo tiver uma ferramenta de legenda nativa, como o YouTube, você poderá usar essa ferramenta para preparar as legendas ou criar um arquivo de transcrição SRT ou VTT formatado adequadamente a ser carregado com o vídeo.

A criação de legendas faz parte do processo de produção de vídeos que podem ser acessados por mais pessoas. Portanto, o proprietário de um vídeo que está sendo adicionado ao GitHub Docs deve fornecer legendas.

Diretrizes para legendas

Sempre que possível, as legendas devem corresponder exatamente às palavras faladas no vídeo. Não parafraseie nem trunque as legendas, a menos que restrições críticas de tempo indiquem que será difícil para alguém ler as legendas no tempo fornecido.

As legendas precisam ser sincronizadas para aparecer aproximadamente ao mesmo tempo que o áudio. Elas sempre devem ser cronometradas para aparecer na tela no momento em que o locutor começar a falar. Para falas rápidas, em que seria difícil ler legendas cronometradas precisamente com o áudio, você pode estender as legendas para permanecer na tela após a conclusão da fala.

Se um vídeo tiver vários locutores, identifique-os nas legendas. Faça isso adicionando o nome do locutor ou um nome descritivo, como Developer, antes do início da frase. Por exemplo: Jimmy: Hello.. Você só precisará fazer isso quando o locutor mudar, não para cada linha de diálogo. Se, por meio dos elementos visuais, for óbvio reconhecer a pessoa que está falando, você não precisará identificar o locutor.

As legendas precisam ter de uma ou duas linhas e, no máximo, 32 caracteres por linha. Coloque cada nova frase em uma nova linha. Caso você precise quebrar uma linha no meio da frase, faça isso em um ponto lógico, por exemplo, após vírgulas ou antes de conjunções como and ou but.

Como adicionar e editar legendas no YouTube

Para os vídeos hospedados no YouTube, confira "Adicionar subtítulos e legendas" e "Editar ou remover legendas" na documentação do YouTube.

Como criar transcrições de vídeo

Para cada vídeo vinculado ou inserido na documentação, precisamos ter uma transcrição descritiva do vídeo. Os artigos de transcrição são formatados como outros artigos, com a matéria frontal YAML e o conteúdo Markdown. Para adicionar uma transcrição ao site do Docs, crie um artigo em content/video-transcripts e inclua a transcrição como o texto do corpo do artigo. Dê ao artigo um nome de arquivo como transcript-VIDEO-NAME.md e uma propriedade de matéria frontal title igual a Transcript - VIDEO NAME. Adicione o artigo ao arquivo index.md no diretório video-transcripts.

Não use variáveis ou reutilizáveis do Liquid para substituir itens como nomes de produtos na transcrição. A transcrição deve ser fiel ao áudio no vídeo, e não devemos alterar nenhum texto na transcrição como resultado da atualização de uma variável ou de um reutilizável após a produção do vídeo.

A criação de transcrições faz parte do processo de produção de vídeos que podem ser acessados por mais pessoas. Portanto, o proprietário de um vídeo que está sendo adicionado ao site da documentação deve fornecer o conteúdo para uma transcrição.

Você pode usar legendas como base para uma transcrição. Edite as legendas para remover os carimbos de data/hora e inclua as informações relevantes detalhadas abaixo. Uma transcrição descritiva inclui uma versão de texto das informações visuais e de áudio necessárias para entender o conteúdo de um vídeo.

Se um vídeo tiver vários locutores, identifique-os na transcrição.
Se o gênero de um falante é conhecido, você pode usar os pronomes que a pessoa prefere ao descrever suas ações. Por exemplo, She points to the computer screen. se o gênero do falante for desconhecido ou irrelevante para o visual que está sendo descrito, você poderá se referir à pessoa usando linguagem neutra.
Formate a transcrição em parágrafos, listas e seções lógicas. Se isso ajudar as pessoas a entender o conteúdo, você poderá adicionar cabeçalhos às seções. Considere como alguém obterá informações da transcrição se também não estiver assistindo ao vídeo
Adicione qualquer texto na tela, elementos visuais relevantes ou sons que não sejam de fala que não estejam incluídos nas legendas. Coloque essas descrições após o texto falado que as acompanha no vídeo. Formate as informações visuais entre colchetes. Por exemplo, [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.].
Adicione uma propriedade product_video à matéria frontal YAML do artigo de transcrição. O valor da propriedade product_video é a URL do YouTube do vídeo. A URL do YouTube do vídeo será exibida como um link externo no artigo de transcrição.
No final da transcrição, escreva End of transcript. e crie um link para a página de aterrissagem do produto que o vídeo aborda usando o padrão For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Confira "Transcrição de texto com a descrição de visuais" na documentação do W3C para ver mais exemplos de transcrições de áudio e elementos visuais.

Vinculação a transcrições de vídeos hospedados externamente

Adicione um link ao artigo com a transcrição de um vídeo na descrição do vídeo na plataforma em que ele está hospedado. Para obter mais informações, confira "Editar as configurações de vídeo" na documentação do YouTube.

Vinculação a transcrições de vídeos inseridos

Em qualquer conteúdo com um vídeo inserido, adicione uma propriedade product_video_transcript abaixo da propriedade product_video na matéria frontal YAML. O valor de product_video_transcript é um link para o artigo de transcrição no diretório video-transcripts.

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

Títulos para vídeos

Os títulos devem ser descritivos e seguir as diretrizes para títulos no modelo de conteúdo. Para obter mais informações, confira "Conteúdo de um artigo do GitHub Docs".

Controle de versão

Se um vídeo for relevante apenas para produtos específicos do GitHub (Gratuito, Pro e Team; GitHub Enterprise Server; e GitHub Enterprise Cloud), precisará ter controle de versão nesses produtos. Use instruções condicionais do Liquid para fazer o controle de versão dos vídeos adequadamente. O controle de versão de condicionais do Liquid poderá precisar ser adicionado quando o conteúdo for criado inicialmente ou poderá precisar ser adicionado quando o conteúdo for atualizado para uma atualização de recursos ou uma versão do GitHub Enterprise. Para obter mais informações sobre instruções condicionais líquidas e controle de versão, consulte "Documentação de controle de versão".

Hospedagem de vídeos

Os vídeos precisam ser hospedados em algum local pertencente ao GitHub e ao qual ele possa permitir acesso à equipe do Docs. Os vídeos não devem acompanhar os usuários nem usar cookies. Atualmente, os vídeos do GitHub são hospedados no YouTube e adicionados à documentação por meio do Modo Avançado de Privacidade pela alteração do domínio da URL inserida de https://www.youtube.com/VIDEO para https://www.youtube-nocookie.com/VIDEO.

Como usar vídeos no GitHub Docs

Neste artigo