Guia de Vídeo de Demonstração de Produto para README

Quando deve um README usar um vídeo de demonstração de produto?

Um vídeo de demonstração de produto para o README é preferível a um GIF curto quando um leitor do repositório precisa de uma sequência visível mais completa do que um loop breve consegue transmitir. A decisão depende da questão técnica do leitor, do movimento necessário para lhe responder e do anfitrião do repositório onde o ficheiro vai ser renderizado. Não é uma afirmação de que o vídeo é sempre melhor, de que todos os README precisam de movimento, ou de que um formato funciona em todos os repositórios.

O GogoScreen começa com o URL de uma aplicação web acessível e uma indicação de uma linha, e depois devolve um candidato em MP4 editado. Pode acrescentar voz sobreposta ajustada aos eventos no ecrã, legendas, aproximações ao clicar, suavização do cursor e cortes de tempos mortos. Estes factos sobre o fluxo de trabalho tornam um candidato em MP4 disponível para revisão. Não estabelecem que um anfitrião o vai incorporar como previsto, nem que um determinado candidato é adequado para a documentação do repositório.

O guia de GIF de demonstração para README já cobre a escolha da representação curta para um leitor que percorre o texto rapidamente. Esta página responde à questão distinta do formato: quando é que um leitor precisa de vídeo, porque a tarefa visível, o detalhe ou a narração opcional exigem mais do que um loop compacto?

Compare vídeo e um GIF curto usando o mesmo fluxo

Use a mesma sequência revista ao comparar formatos. Caso contrário, a escolha torna-se numa comparação de duas histórias diferentes, em vez de uma verdadeira decisão de formato. Verifique o primeiro fotograma, o detalhe legível do produto, a ação, o resultado, o peso do ficheiro, o comportamento de reprodução e o suporte do anfitrião do repositório. Um vídeo pode preservar mais detalhe ou fornecer orientação falada opcional. Um GIF pode ser mais adequado quando a ação é óbvia sem controlos nem áudio.

O guia de fotograma de cartaz de vídeo de demonstração ajuda a selecionar um primeiro olhar fiel para um espectador que nunca inicia a reprodução. O guia de vídeo de demonstração de produto sem som verifica se o fluxo visível transmite a sua prova central sem áudio. Estas revisões importam antes de escolher vídeo, porque um leitor de README pode não premir reproduzir nem ouvir a narração.

Não descreva o GogoScreen como um gerador de GIFs. Esta é uma escolha de formato a partir de um ficheiro de origem revisto. O guia de legendas para vídeo de demonstração de produto analisa palavras legíveis que correspondem a eventos visíveis. O guia de voz sobreposta para vídeo de demonstração de produto analisa a narração ajustada ao mesmo fluxo de navegador.

Proteja a documentação e o limite privado

Mantenha o exemplo do repositório livre de material privado

Não use aplicações de clientes, URLs de clientes, conteúdos multimédia de clientes, nomes, credenciais nem material privado para criar um exemplo de README mais convincente. Use um contexto controlado, que não seja de clientes. Quando o início de sessão for necessário para um fluxo selecionado, pode ser fornecida uma conta de demonstração descartável através do processo aprovado. Quem escreve e quem revê não pedem, recebem, copiam nem inspecionam credenciais. No GogoScreen, as credenciais são cifradas, utilizadas para uma única renderização e depois eliminadas. Se for planeado primeiro um storyboard, as credenciais ficam cifradas durante essa sessão e são eliminadas, no máximo, duas horas após a última utilização.

Se a rota, o acesso ou o fluxo selecionado forem inadequados, altere o menor elemento de preparação antes de considerar outro candidato. O guia de falha de renderização de vídeo de demonstração ajuda a diagnosticar o problema. O guia de nova tentativa de vídeo de demonstração de produto regista a alteração de preparação para outra tentativa. Aproximadamente uma em cada cinco renderizações falha ou precisa de nova tentativa, pelo que um ficheiro devolvido nunca deve ser tratado como prova automática de documentação.

Escolha o público do repositório antes de outro canal

Para distribuição para além do repositório, o guia de vídeo de demonstração para o Show HN considera um público técnico de lançamento, e o guia de vídeo de produto para página de destino considera um visitante a avaliar uma promessa da página. São tarefas diferentes de ajudar alguém a inspecionar um repositório antes da instalação.

Leia os preços, a informação de privacidade e os termos antes de um pedido. Visite o centro de guias para decisões relacionadas. Um vídeo de demonstração de produto para README merece o seu lugar quando ajuda um leitor de repositório a compreender um fluxo de trabalho funcional, enquanto a documentação permanece completa sem ele.