Documentação que vira vídeo: o que aprendemos gerando releases e runbooks

Resumo para quem tem pressa: passamos a gerar vídeos curtos a partir dos nossos próprios arquivos de documentação, sem gravar nada. Funcionou bem para release notes e para runbooks de procedimento. Falhou em três situações específicas que descrevo no final. O ponto que mais importa não é a ferramenta: é manter o documento como fonte da verdade e tratar o vídeo como artefato derivado, igual a um build.

Somos um time de sete pessoas em uma empresa de logística. Mantemos uma API que integra transportadoras e um painel interno usado por gente de operação que não é técnica. Esse último detalhe explica quase tudo o que vem a seguir.

O problema não era escrever a documentação

A documentação existia e estava razoavelmente organizada. Seguimos a divisão do Diátaxis desde 2024: tutorial, how-to, referência e explicação em lugares diferentes. Isso resolveu bastante coisa para o time técnico.

Não resolveu nada para o pessoal de operação.

O sintoma clássico: toda release que mudava algo no painel gerava a mesma sequência. Publicávamos o changelog, mandávamos o link no canal, e três dias depois chegavam quatro chamados perguntando exatamente o que estava escrito no changelog. Não é preguiça. É que ninguém lê um documento técnico no meio do expediente para descobrir se aquilo afeta o trabalho dele.

Tentamos resumo em bullet, tentamos GIF, tentamos áudio no canal. O que teve resposta melhor foi vídeo curto. E aí bateu o problema de sempre: ninguém do time queria gravar vídeo toda semana, e com razão.

Por que vídeo, e quando não

Vale separar as coisas, porque virou moda transformar tudo em vídeo e boa parte disso é desperdício.

Vídeo funciona quando o conteúdo é sequencial e o leitor precisa saber se aquilo o afeta. Release notes se encaixam: dois minutos assistidos passivamente resolvem uma dúvida que o texto só resolveria se a pessoa lesse até o fim.

Vídeo funciona para procedimentos que são executados raramente. Nosso runbook de rotação de credenciais é usado a cada seis meses, e a cada seis meses alguém lê errado a ordem dos passos.

Vídeo não funciona para referência de API. Ninguém quer assistir a um vídeo para descobrir o formato de um payload. Isso é consulta, e consulta é texto pesquisável.

Vídeo também não funciona para explicação conceitual longa. Quem precisa entender por que escolhemos uma arquitetura vai querer ler, voltar, comparar.

Ficamos com dois casos de uso: release e runbook. Ignoramos o resto.

O fluxo que montamos

A regra que definimos antes de escolher qualquer ferramenta: o vídeo tem que ser gerado a partir do arquivo que já mantemos, e não de um roteiro escrito à parte. Roteiro à parte vira mais uma coisa para manter desatualizada.

Usamos o Leadde.ai para essa etapa, basicamente porque ele parte do documento. Aceita .pptx, .pdf, .doc, .docx e .txt até 500 MB, e quando o arquivo tem imagem ou diagrama dentro, ele avalia o que dá para aproveitar e leva para o vídeo. Nossos diagramas exportados do repositório entraram sem retrabalho.

O processo hoje:

Exportamos o markdown da release em .txt ou .pdf. Isso é um passo de build, não trabalho manual.

Subimos o arquivo e mantemos sempre o mesmo apresentador e o mesmo template. Existem mais de 200 avatares e mais de 50 templates, e a escolha só importa uma vez: consistência entre vídeos vale mais que a aparência de qualquer um deles isoladamente.

Escolhemos a duração por preset. Resumo de 1 a 3 minutos, equilibrado de 3 a 5, aprofundado de 5 a 7, e completo que acompanha o tamanho do material. Release usa resumo. Runbook usa equilibrado.

Preenchemos os campos de contexto: estilo narrativo, público, perfil de quem apresenta, objetivo. Deixamos vazio nas primeiras tentativas e o roteiro saiu tecnicamente correto e inútil para operação. Colocando "público: analistas de operação sem conhecimento técnico", o mesmo changelog virou um texto que explica o impacto no fluxo de trabalho em vez de listar endpoints.

Revisamos o roteiro antes de gerar. A plataforma monta a estrutura e o texto da narração, e oferece abrir o editor ou gerar direto. Nunca geramos direto, e explico o motivo na próxima seção.

O que ainda exige revisão humana

Três coisas, todas descobertas na prática.

Primeiro, os termos internos. O nome dos nossos serviços é ruim de pronunciar e a primeira versão leu tudo como palavra em inglês. Dá para corrigir a pronúncia uma vez e aplicar a todos os roteiros. Vinte minutos no começo economizaram retrabalho em todos os vídeos seguintes.

Segundo, as ressalvas. Changelog costuma ter frases do tipo "isso vale apenas para contratos migrados". Ao resumir, é exatamente esse tipo de cláusula que some primeiro. Nossa checagem obrigatória é procurar no documento original todo "apenas", "exceto" e "somente" e conferir se sobreviveu no roteiro.

Terceiro, o tom da abertura. As duas primeiras frases saem sempre mais institucionais do que a gente fala. Reescrevemos à mão, sempre. Custa dois minutos.

Para quem quiser melhorar a escrita antes de automatizar qualquer coisa, os cursos de technical writing do Google são gratuitos e resolvem metade dos problemas que a gente atribuía à ferramenta.

Versionamento: o documento continua sendo a fonte da verdade

Essa foi a decisão de arquitetura do processo, e é o que evita a bagunça.

O vídeo não é editado depois de gerado. Se o conteúdo mudou, muda o documento no repositório e gera de novo. O vídeo antigo é substituído, não corrigido. Tratamos exatamente como tratamos um artefato de build: não se edita o binário, se corrige o fonte.

Isso tem uma consequência prática boa: o vídeo nunca fica em desacordo com a documentação, porque ele é uma projeção dela. E tem uma consequência chata: se você gerar vídeo a partir de um documento ruim, você amplifica o problema. Reescrevemos quatro runbooks antes de converter, e esse trabalho foi maior do que toda a parte de vídeo somada.

Também mantivemos o texto sempre disponível ao lado do vídeo. Ninguém deveria ser obrigado a assistir a nada para ter uma informação.

Números depois de três meses

Onze vídeos de release e seis de runbook.

Tempo médio por vídeo: 22 minutos, sendo a maior parte revisão de roteiro. A geração em si leva poucos minutos.

Chamados repetidos após release caíram de forma perceptível. Não tenho número limpo para mostrar, porque mudamos o template de abertura de chamado no mesmo período e não dá para separar as duas causas. Prefiro dizer isso a inventar uma porcentagem.

O dado que me convenceu foi outro: o painel de analytics mostra visualizações, tempo médio assistido e taxa de conclusão. Nossos vídeos de release têm conclusão bem alta, e o de rotação de credenciais tinha uma queda sempre no mesmo trecho. Fomos ver: o passo 4 do runbook estava ambíguo desde 2023. O texto nunca nos contou isso, porque documento não avisa onde a pessoa desistiu.

O que deu errado

Vale registrar os três casos em que abandonamos.

O primeiro foi o vídeo de setup do ambiente local. Exige mostrar terminal e IDE, a ferramenta não grava tela, e a alternativa de colocar prints anotados no documento ficou pior que o texto puro. Voltamos para texto.

O segundo foi uma tentativa de gerar vídeo direto do diff da release, sem passar por um documento escrito por humano. Saiu uma narração descrevendo commits, o que é inútil para operação. Vídeo não corrige a falta de curadoria.

O terceiro foi tentar cobrir release de correção pequena. Gerar vídeo de duas frases é desperdício e polui o canal. Definimos um critério: só vira vídeo se houver mudança visível para quem usa o painel.

Uma última observação honesta: o apresentador gerado é adequado, não impressionante. Para comunicação interna e para clientes de operação isso nunca foi levantado como problema. Para material de marketing externo eu pensaria mais.

Perguntas que apareceram no time

Não daria para fazer isso com TTS e slides?
Daria, e chegamos a montar um script para isso. Desistimos porque o custo de manutenção do script ficou parecido com o problema original, e porque a revisão do roteiro continuava sendo manual do mesmo jeito.

E se a ferramenta sumir amanhã?
O ativo continua sendo o documento no repositório. Perderíamos a projeção, não a fonte. Foi condição para adotar.

Dá para restringir acesso?
Os vídeos publicados aceitam proteção por senha. Usamos nos runbooks que citam nomes de sistemas internos.

Funciona para conteúdo em outros idiomas?
Dá para gerar uma versão traduzida a partir do mesmo vídeo, incluindo o texto que aparece na tela, e existem 88 idiomas. Fizemos uma versão em espanhol para o time do Chile e mandamos revisar com alguém de lá antes de publicar. Tradução automática resolve o volume, não a terminologia.

Precisa de máquina boa?
É uma aplicação web pensada para desktop, e funciona melhor no Chrome. Não tentamos usar em tablet.

Se for testar

Não comece pela release mais importante. Comece pelo procedimento que mais gera pergunta repetida, de preferência um que você já sabe que está mal escrito.

E teste o segundo ciclo, não o primeiro. Gere o vídeo, mude uma frase no documento e refaça o caminho todo até substituir o link. É esse loop que você vai repetir por anos.