Uma breve gravação pode explicar uma interação que leva vários parágrafos para ser descrita: configuração de um painel, reprodução de um bug ou conclusão de um fluxo de integração. Mas enviar uma gravação é apenas o primeiro passo.
Os desenvolvedores ainda precisam considerar o texto legível da interface, legendas precisas, tamanho do download, controles do teclado e o que acontece quando o vídeo não consegue carregar. Essas decisões determinam se uma demonstração se torna uma documentação útil.
Este tutorial apresenta um fluxo de trabalho prático para preparar e publicar um vídeo junto com a documentação escrita de um aplicativo da web.
1. Projete a demonstração em torno de uma tarefa
Comece com um resultado específico, como “Criar um token de API de teste e verificar a solicitação”. Uma demonstração focada é mais fácil de acompanhar e atualizar do que um tour por cada recurso.
Antes de gravar, escreva uma pequena sequência:
- Indique as condições iniciais.
- Execute a tarefa.
- Mostre o resultado esperado.
- Explique uma falha comum e sua recuperação.
Use uma conta de demonstração e dados sintéticos. Verifique a tela em busca de credenciais, registros de clientes, notificações e guias do navegador antes de capturá-la.
Para tutoriais técnicos, forneça comandos e códigos como texto selecionável ao lado do vídeo. Os espectadores não deveriam ter que pausar uma gravação para transcrever um comando do terminal.
2. Prepare a gravação para uma página de documentação
Capture com uma resolução que mantenha os rótulos da interface legíveis no tamanho de exibição pretendido. Uma gravação completa da área de trabalho pode parecer nítida em seu monitor, mas torna-se difícil de ler dentro de uma coluna estreita de documentação.
Amplie a área relevante do aplicativo, remova pausas desnecessárias e mantenha contexto suficiente para que os espectadores entendam cada ação.
AS ÁGUAS é uma plataforma de criação e edição de vídeo baseada em navegador com ferramentas para gravação de tela, corte e recorte de clipes, adição de texto, geração de legendas e limpeza de áudio. Em um fluxo de trabalho de documentação do desenvolvedor, esses recursos podem ajudar a preparar uma reprodução de bug gravada, um passo a passo de integração ou uma demonstração de recurso para publicação.
Por exemplo, um desenvolvedor que explica um fluxo de autenticação poderia usar veed para editar uma gravação feita com uma conta de demonstração, remover pausas entre as etapas, adicionar um rótulo identificando o ambiente de teste e revisar as legendas geradas em relação à narração real. Mantenha as mensagens de erro e as etapas de recuperação na versão final: elas geralmente contêm as informações mais úteis para quem segue o tutorial.
Use o editor para preparar o conteúdo e, em seguida, avalie os ativos exportados em relação aos requisitos do seu site. Verifique a legibilidade do texto, a precisão das legendas, o tamanho do arquivo e a compatibilidade de reprodução. Editar um clipe e entregá-lo de forma confiável em um aplicativo da web exige verificações diferentes.
Mantenha uma gravação de origem editável. Quando o aplicativo muda, essa fonte facilita a substituição de um segmento ou a produção de uma exportação revisada.
3. Use controles de vídeo HTML nativos
Para um clipe de documentação, comece com o player integrado do navegador. Evita o trabalho de implementar toda uma interface de controle.
SitePoints guia para incorporar vídeo com HTML5 fornece informações básicas sobre a marcação básica. O exemplo abaixo adiciona um pôster, uma faixa de legenda e links que permanecem disponíveis fora do player:
<section aria-labelledby="demo-heading">
<h2 id="demo-heading">Create a test API token</h2>
<p>A short walkthrough using a demonstration account.</p>
<video
controls
playsinline
preload="none"
width="1280"
height="720"
poster="/media/create-token-poster.webp"
>
<source
src="/media/create-token.mp4"
type="video/mp4"
>
<track
kind="captions"
src="/media/create-token.en.vtt"
srclang="en"
label="English"
default
>
Your browser does not support embedded video.
</video>
<p>
<a href="/docs/create-token-transcript.html">
Read the transcript and commands
</a>
·
<a href="/media/create-token.mp4">
Open the video file
</a>
</p>
</section>
Torne o player responsivo sem perder suas proporções:
video {
display: block;
width: 100%;
height: auto;
background: #111;
}
Os atributos de largura e altura estabelecem as proporções intrínsecas do vídeo, ajudando o navegador a reservar espaço. O CSS permite caber em um contêiner menor.
Os links de download e transcrição ficam fora do elemento de vídeo porque o conteúdo dentro dele não é uma interface de recuperação confiável para cada falha de reprodução.
4. Faça das legendas um recurso separado e revisável
As legendas devem incluir conteúdo falado e sons relevantes. As legendas geralmente focam no diálogo ou na sua tradução.
Para vídeo HTML nativo, use um arquivo WebVTT:
WEBVTT
00:00:00.000 --> 00:00:04.000
Open Settings, then select API access.
00:00:04.000 --> 00:00:08.000
Choose Create test token and copy the value.
00:00:08.000 --> 00:00:12.000
Run the example request with the test token.
Salve isso como create-token.en.vttcorrespondendo ao URL da faixa. Sirva com o text/vtt tipo de conteúdo.
Artigo do SitePoint sobre Fragmentos de vídeo HTML5, legendas e miniaturas dinâmicas apresenta faixas de texto. Para detalhes do formato atual, consulte Documentação WebVTT do MDN.
Ao preparar legendas no Veed, revise os carimbos de data e hora, mudanças de orador, pontuação e nomes técnicos antes de publicar. Uma legenda gerada automaticamente que transforma “npm” em uma palavra comum pode enganar um iniciante.
Mantenha as legendas selecionáveis através do player, em vez de depender apenas do texto gravado na imagem. Uma faixa separada pode ser atualizada sem recodificar o vídeo e oferece suporte a idiomas adicionais.
5. Explique informações visuais significativas
As legendas por si só não transmitem uma ação que aparece apenas na tela.
Em vez de narrar “clique aqui”, diga “selecione o acesso à API na barra lateral Configurações”. Descreva também o resultado importante: “O painel de resposta exibe o status 200.”
Uma transcrição útil inclui a explicação falada e etapas visuais essenciais. Quando informações visuais importantes permanecerem ausentes da narração, avalie se é necessária uma versão audiodescrita.
SitePoints introdução às descrições de áudio acessíveis explica o propósito destas informações adicionais. Teste o método de entrega em seus navegadores compatíveis, em vez de presumir que uma faixa de descrições fornecerá saída falada em todos os lugares.
6. Escolha uma estratégia de carregamento deliberadamente
O exemplo usa preload="none" porque o vídeo complementa a documentação. Ele pede ao navegador para evitar o pré-carregamento de dados de vídeo, embora o pré-carregamento seja uma dica e não uma garantia absoluta.
Um pôster ainda é carregado separadamente. Comprima-o e use uma imagem que comunique o que a demonstração cobre.
Para um vídeo que é o conteúdo principal, preload="metadata" pode ser apropriado ao mostrar assuntos antecipados de duração. Para uma página contendo muitos clipes, considere anexar fontes de mídia somente quando um visualizador solicitar um clipe específico.
Evite presumir que um player visualmente pequeno significa um download pequeno. Codificação, duração, resolução e taxa de bits determinam o tamanho da transferência. Meça as solicitações reais com o painel Rede do navegador. O web.dev guia para vídeo de carregamento lento explica opções de carregamento adicionais.
Comece com a reprodução iniciada pelo usuário. Uma demonstração técnica é mais fácil de acompanhar quando os espectadores escolhem quando ela começa.
7. Lidar explicitamente com falhas de reprodução
Um vídeo pode falhar mesmo quando a página de documentação circundante carrega corretamente. Adicione uma mensagem de status visível enquanto mantém a transcrição e o link direto do arquivo disponíveis.
Coloque esta mensagem após o vídeo no exemplo anterior:
<p id="video-status" role="status"></p>
Em seguida, adicione este script após a seção:
const video = document.querySelector('video');
const message = document.getElementById('video-status');
function reportMediaError() {
if (!video.error) return;
message.textContent =
'The video could not play. Use the transcript or direct video link below.';
}
video.addEventListener('error', reportMediaError);
video.addEventListener('loadeddata', () => {
message.textContent = '';
});
video.querySelectorAll('source').forEach(source => {
source.addEventListener('error', () => {
message.textContent =
'The video source could not load. The transcript is available below.';
});
});
reportMediaError();
Este exemplo pressupõe um vídeo e uma fonte, correspondendo à marcação anterior. Se você adicionar codificações alternativas, uma falha de uma fonte não deverá ser relatada como uma falha completa de reprodução enquanto outra fonte permanecer utilizável. Acompanhe os resultados alternativos antes de mostrar a mensagem final.
O Propriedade de erro HTMLMediaElement expõe um MediaError quando existe. Use seu código como evidência de diagnóstico, juntamente com inspeção de rede; não identifica necessariamente a causa subjacente por si só.
Trate cada demonstração publicada como um pequeno lançamento. Um manifesto pode manter o vídeo, as legendas, o pôster e a transcrição associados à versão do aplicativo que descrevem:
{
"id": "create-test-token",
"appVersion": "2.4",
"mediaRevision": 3,
"video": "/media/create-token.r3.mp4",
"captions": "/media/create-token.r3.en.vtt",
"poster": "/media/create-token.r3.webp",
"transcript": "/docs/create-token.r3.html"
}
Alterar o URL do ativo quando seu conteúdo muda torna o comportamento do cache mais fácil de raciocinar. Carregue todos os ativos referenciados antes de publicar o manifesto ou a atualização da documentação e retenha os ativos mais antigos enquanto as páginas em cache ainda podem referenciá-los.
O tempo da legenda pertence a uma edição específica. Remover cinco segundos do início de um vídeo sem atualizar suas legendas altera cada sugestão subsequente. Incluir sincronização de legendas na revisão sempre que a gravação for alterada.
Mantenha manifestos, legendas e transcrições baseados em texto no controle de versão. Para gravações grandes, use armazenamento de mídia adequado ao tamanho e ao fluxo de trabalho da sua equipe.
9. Teste a experiência publicada
Valide a página final com seus arquivos de mídia implantados:
| Verificar | O que verificar |
|---|---|
| Teclado | Os controles de reprodução e legenda são acessíveis e operáveis |
| Legendas | O texto é preciso, sincronizado e legível |
| Janela de visualização estreita | Os detalhes da interface permanecem compreensíveis |
| Conexão lenta | A página permanece utilizável enquanto a mídia é carregada |
| Solicitação falhada | Links de transcrição e arquivos diretos permanecem disponíveis |
| Revisão de conteúdo | A gravação corresponde à versão documentada do aplicativo |
Verifique também o arquivo codificado nos navegadores suportados. Uma extensão MP4 identifica um contêiner; a compatibilidade de reprodução depende dos codecs contidos nele.
Se a mídia ou as legendas usarem uma origem separada, verifique a configuração CORS aplicável. Prefira uma configuração simples de mesma origem para uma implementação inicial e use Referência de vídeo do MDN ao configurar a entrega entre origens.
Mantenha vídeos como documentação
Armazene a gravação de origem, a exportação final, as legendas, a transcrição e o pôster como ativos relacionados. Atribua um proprietário e registre qual versão do aplicativo a demonstração abrange.
Uma página de vídeo útil combina uma demonstração focada com texto legível, legendas verificadas, carregamento previsível e links de recuperação funcionais. Manter essas partes juntas dá aos desenvolvedores uma referência que eles podem observar, pesquisar, copiar e revisitar conforme o aplicativo evolui.
