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. Vídeos nunca devem ser a única maneira de comunicar informações, pois são mais difíceis de serem 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 landing page nos documentos.

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 esta lista de verificação para rapidamente determinar se um vídeo pode ser apropriado para adicionar a um artigo ou a uma página de destino.

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 isso for relevante apenas para um produto ou recurso específico, você deve versioná-lo. 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. Os vídeos devem ser atraentes e animadores. Vídeos 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ível público-alvo**: pessoas que desejam saber se um recurso é útil para suas metas e pessoas novas no GitHub, tentando entender o que os produtos fazem

        **Possíveis locais na documentação**: páginas de aterrissagem e guias

Vídeos de destaque

        **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. A duração 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 funções que mudam rapidamente e 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 legendas ocultas. Confira Como criar legendas de vídeo abaixo para obter mais informações
Nenhum elemento gráfico se sobrepõe ao 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 do que acontece cena a cena revisadas. 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 houver uma mudança de falante, 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 o frontmatter 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 componente 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á usar o pronome "eles" de forma singular para se referir à pessoa.
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 ao frontmatter YAML do artigo transcrito. 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 destino do produto que o vídeo aborda, seguindo o padrão For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Confira Transcrição de texto com descrição de elementos visuais na documentação do W3C para mais exemplos de transcrições de áudio e 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.

Links para transcrições de vídeos embutidos

Em qualquer conteúdo com um vídeo inserido, adicione uma propriedade product_video_transcript abaixo da propriedade product_video no frontmatter 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 saber mais, 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), o vídeo deverá ser adaptado para as versões desses produtos. Use instruções condicionais do Liquid para versionar adequadamente os vídeos. 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.

Neste artigo