Guia de GIF de Demonstração para README

Onde deve ficar o ficheiro em relação à instalação?

Coloque o ficheiro curto depois da descrição simples do que o projeto faz e antes da secção de instalação que ajuda a explicar. Um leitor deve conseguir compreender o ficheiro sem primeiro percorrer um tutorial. A frase envolvente pode nomear o fluxo de trabalho mostrado, enquanto os comandos de instalação permanecem como texto escrito e copiável abaixo dele.

Não coloque o ficheiro entre dois passos que o leitor tenha de copiar. O movimento interrompe a leitura rápida quando divide um percurso de configuração. Não o coloque tão abaixo no README que um visitante já tenha passado o ponto de decisão. A localização correta é determinada pela estrutura do repositório, não por uma regra universal de que todos os README precisam de movimento no topo.

Reveja-o no README renderizado, e não apenas num editor. Uma representação que parece aceitável num ficheiro local pode ser demasiado larga, demasiado lenta a carregar, ou pouco clara quando exibida pelo anfitrião do repositório. Verifique a pré-visualização do repositório nas larguras que um leitor provavelmente vai usar, incluindo uma janela de visualização estreita.

Como decidir entre um GIF e outra representação?

A expressão GIF de demonstração para README nomeia uma necessidade do leitor, não uma promessa sobre um formato técnico específico. Um GIF pode fazer loop sem controlos e pode funcionar em muitas pré-visualizações de repositórios, mas também pode ter um peso de ficheiro elevado e um detalhe visual limitado. Um ficheiro de vídeo pode ser mais pequeno para o mesmo conteúdo em movimento, mas depende do anfitrião, do comportamento de reprodução e de o leitor do repositório conseguir aceder aos controlos. Uma imagem estática é muitas vezes mais clara quando a própria ação não precisa de movimento.

Faça esta escolha com um pequeno registo de decisão. Compare o candidato real no tamanho de visualização previsto. Verifique a clareza do primeiro fotograma, o detalhe legível, o peso do ficheiro, o comportamento de carregamento, o comportamento de loop quando usado, e a explicação acessível. O áudio não deve ser necessário para o significado essencial, porque as pré-visualizações de repositórios podem não o reproduzir automaticamente. Se o áudio contiver voz sobreposta gerada e for publicado, o requisito de divulgação e marcação aplicável tem de ser revisto separadamente.

Não afirme que o GogoScreen exporta GIFs, a menos que essa capacidade esteja verificada e aprovada para texto de produto. O guia de vídeo de demonstração de produto para README cobre quando o vídeo é preferível a um GIF curto na documentação do repositório. O guia de alternativa a GIF de demonstração de produto faz a mesma decisão de representação para um fluxo de app fora do contexto do repositório. Esta página descreve, em vez disso, como escolher uma representação para o README a partir de um resultado de origem aprovado. A questão é se o ficheiro ajuda um leitor a compreender o repositório, não se um formato soa mais familiar numa pesquisa.

Checklist de pré-visualização do README

Execute esta checklist no contexto real de renderização do README. Define trabalho de revisão que ainda tem de acontecer, não prova já concluída.

1. O ficheiro mostra um fluxo de trabalho relevante para o repositório.
2. O primeiro fotograma identifica o contexto do produto sem áudio.
3. A ação e o resultado mantêm-se legíveis na largura renderizada do README.
4. O ficheiro fica depois da explicação do projeto e antes da sequência de instalação que apoia.
5. Os comandos de instalação, o texto de acessibilidade e as limitações mantêm-se legíveis em redor.
6. O formato escolhido foi revisto quanto ao peso do ficheiro, ao carregamento, ao comportamento do loop quando aplicável e ao suporte de reprodução do anfitrião.
7. A legenda descreve o fluxo de trabalho visível, sem fazer uma afirmação mais ampla.
8. Não aparece material de clientes, credenciais, URL de cliente nem conteúdo multimédia de cliente.
9. A data de captura, a compilação, a escolha de representação, o revisor, o resultado e o registo de novas tentativas são mantidos.

Se a pré-visualização tornar o README mais lento ou mais difícil de percorrer, remova o ficheiro ou escolha outra representação. Uma página de repositório beneficia de clareza, não de movimento pelo movimento.