Como ditar um relatório de bug que outra pessoa consiga reproduzir

“Quebrou de novo” é um relato sincero. Mas também é difícil de corrigir a partir dele. Quando você abre o rastreador de problemas, a tela, o botão e o resultado exatos já podem ter se confundido na memória. Ditar um relatório de bug ajuda a preservar esses detalhes enquanto ainda estão frescos, mas só se você der uma estrutura ao relato antes de começar.

Este é um fluxo de trabalho curto para transformar uma falha observada em um relatório que outra pessoa consiga reproduzir. Ele funciona tanto para testar um projeto pessoal quanto para registrar um problema no trabalho ou ajudar a manter uma ferramenta de código aberto. Você ainda precisará digitar os comandos exatos e revisar o relatório final. A voz serve para contar o que aconteceu, não para inventar evidências.

Comece pela falha, não por um diagnóstico

Relatórios de bugs se desviam do objetivo quando o título anuncia uma teoria: “O cache do banco de dados está quebrado”. Talvez você esteja certo, mas quem investiga precisa primeiro saber o que foi observado. Um título melhor descreve a ação e o resultado: “Salvar um rascunho apaga o idioma selecionado nas Configurações”. Isso pode ser testado sem que a pessoa precise aceitar sua teoria sobre a causa.

A mesma regra ajuda na hora de ditar. Diga em uma frase qual tarefa você tentava concluir e, em outra, o que o software fez em vez disso. Não comece com um longo histórico da sua semana nem com um palpite sobre qual subsistema falhou. Se o problema é intermitente, diga isso. Se ocorre toda vez no seu computador, diga também, mas não afirme que ocorre com todo mundo.

O guia do GitHub para criar uma issue explica como inserir um título e uma descrição claros e observa que o repositório pode oferecer um modelo de issue. Use esse modelo quando houver um. A estrutura ditada abaixo ajuda a reunir os fatos antes de preencher os campos; ela não é motivo para ignorar as instruções do projeto.

A nota de voz com cinco campos

Abra um rascunho privado em branco em vez de registrar o problema diretamente em um rastreador público. Posicione o cursor no editor e dite cinco campos curtos, cada um em uma nova linha. A primeira versão deve soar como o relato de uma testemunha, não como uma nota de lançamento cuidadosamente editada:

1. Contexto: O que você tentava fazer? Indique a página, o recurso ou a operação.
2. Etapas: Quais ações produziram a falha? Numere-as na ordem.
3. Esperado: Qual resultado você esperava razoavelmente?
4. Real: O que aconteceu na tela? Só cite uma mensagem de erro curta depois de conferi-la.
5. Abrangência: Quando aconteceu, em qual ambiente e você consegue repetir?

Aqui está um modelo para copiar e colar. Substitua cada trecho entre colchetes por um detalhe observado. Se não souber preencher um campo, escreva “não verificado” em vez de inventar uma resposta plausível.

Título: [ação] causa [resultado observado]
Contexto: Eu tentava [objetivo] em [recurso/página].
Etapas para reproduzir:
1. [estado inicial exato]
2. [primeira ação]
3. [ação seguinte]
Esperado: [o que deveria ter acontecido]
Real: [o que aconteceu, incluindo o texto de erro conferido]
Frequência: [uma vez / às vezes / em todas as tentativas neste dispositivo]
Ambiente: [versão do aplicativo, sistema operacional e navegador, se relevante]
Evidências: [captura de tela segura ou registro sem dados sensíveis, se útil]

Não leia os colchetes em voz alta esperando que virem uma estrutura de texto. Primeiro, coloque os títulos no editor; depois, dite o conteúdo de cada campo. Se você usa um teclado de voz para computador, como o Talkpad no macOS ou no Windows, posicione o cursor no rascunho privado e dite um campo por vez. Assim fica mais fácil parar, inspecionar e corrigir cada parte antes de publicar.

Reproduza uma vez e narre os cliques

A memória transforma uma sequência em resumo. “Mudei uma configuração e a página travou” pode omitir a atualização da página, a troca de conta ou o formulário não salvo. Se for seguro, repita a sequência com o rascunho aberto ao lado do aplicativo afetado. Faça uma pausa após cada ação e registre o que fez. Não provoque repetidamente um bug que apaga dados ou cobra dinheiro só para melhorar a redação.

Descreva as etapas literalmente: “Abra Configurações, escolha Espanhol, clique em Salvar e abra Configurações novamente”. Evite “entre nas preferências de sempre e faça aquilo”. Se o aplicativo tiver vários botões Salvar, indique o painel. Se o bug só aparecer após recarregar a página, inclua essa ação. Uma pessoa que nunca viu sua tela deve conseguir seguir as etapas sem precisar perguntar qual clique faltou.

Você pode ditar a narrativa, mas use o teclado para sequências de caracteres delicadas. Um modelo pode transformar o nome de um pacote em palavras comuns, alterar as maiúsculas de uma opção ou omitir um sinal de menos. Cole um rastreamento de pilha ou erro do aplicativo depois de conferi-lo, em vez de ditá-lo. O mesmo vale para uma versão precisa, como 1.4.12. Consulte nosso guia de nomes e termos técnicos para palavras menos arriscadas que ainda exigem uma revisão cuidadosa.

Separe o esperado do resultado real

É aqui que o relatório se torna útil. “O formulário falhou” não diz quase nada a quem investiga. “Depois que cliquei em Salvar, apareceu a confirmação, mas o idioma voltou para inglês quando abri as Configurações novamente” descreve uma diferença observável. O resultado esperado pode ser igualmente simples: “O idioma salvo ainda deveria ser espanhol quando eu abrisse as Configurações novamente”.

Não coloque uma proposta de correção disfarçada no campo do resultado esperado. “O aplicativo deveria usar outro cache” é uma sugestão de implementação, não uma expectativa visível para o usuário. Coloque qualquer hipótese em uma nota claramente identificada no final e mantenha a incerteza. Outra pessoa pode descobrir que a causa é uma resposta da API, um cliente com dados desatualizados ou algo completamente diferente.

Quando o reconhecimento de voz erra uma negação, o relatório pode acabar dizendo o contrário. Compare “a caixa de diálogo não fechou” com “a caixa de diálogo fechou”. Releia essas frases na tela antes de registrar o problema. Por isso, nosso método de revisão que prioriza os riscos confere negações, números e nomes antes de fazer ajustes de estilo.

Inclua o ambiente sem montar um dossiê pericial

O mínimo útil sobre o ambiente geralmente inclui a versão do aplicativo, o sistema operacional, o navegador se o bug ocorrer nele e qualquer configuração de recurso necessária para reproduzi-lo. Diga se consegue reproduzir em uma sessão limpa ou em outro dispositivo apenas se realmente testou. O horário ou as condições da rede importam quando alteram o resultado; caso contrário, só acrescentam ruído.

Examine uma captura de tela antes de anexá-la. Nomes de usuário, endereços de e-mail, tokens, registros de clientes e prévias de conversas podem estar escondidos nos cantos. Recorte a área relevante ou desfoque os detalhes sensíveis com um editor confiável. Os registros merecem a mesma revisão. Se o rastreador de problemas for público, presuma que o anexo também será. Para dúvidas sobre regras no trabalho, consulte nossa lista de verificação de privacidade para digitação por voz antes de ditar material confidencial em qualquer ferramenta.

O Talkpad pode inserir um rascunho ditado no aplicativo em que o cursor estiver, mas não verifica se uma captura de tela é segura nem se um rastreamento de pilha está correto. Essas verificações cabem a você. Se as regras da empresa restringirem o processamento por voz de dados de incidentes, siga essas regras e escreva manualmente as partes sensíveis.

Revise em duas passadas antes de registrar

A primeira passada é para verificar a capacidade de reprodução. Comece no estado indicado e siga as etapas ao pé da letra. A falha aparece? Os resultados esperado e real são diferentes e estão claros? Você omitiu uma etapa de login ou uma configuração que altera o resultado? Se não conseguir reproduzir novamente, ajuste o campo de frequência para refletir isso, em vez de esconder a incerteza.

A segunda passada é para verificar os riscos. Confira as versões e o texto do erro nas fontes originais. Remova informações secretas do corpo e dos anexos. Substitua especulações por fatos observáveis ou identifique-as como hipóteses. Encurte a introdução se ela atrasar a chegada às etapas. Você pode usar nosso guia de edição de rascunhos ditados quando a primeira versão chegar como um bloco de fala, e não como campos organizados.

Um relatório útil não precisa ser longo. Alguns bugs exigem três etapas e duas frases; outros precisam de um exemplo controlado. Evite acrescentar texto só para aumentar o tamanho. O objetivo é permitir que outra pessoa reproduza o comportamento e entenda por que você esperava algo diferente. Se não consegue explicar o estado inicial, investigue um pouco mais antes de publicar.

Perguntas frequentes

Posso usar ditado para escrever um relatório de bug?

Sim. Dite o contexto, as etapas de reprodução e a diferença entre o comportamento esperado e o real em um rascunho privado. Digite e confira os comandos, as mensagens de erro, as URLs e os números de versão exatos antes de compartilhar.

O que um relatório de bug deve incluir?

Inclua um título descritivo, o contexto inicial, etapas em ordem, o resultado esperado, o resultado real, o ambiente relevante e evidências seguras, se necessário. Siga o modelo de issue do repositório, se houver um.

Como relatar um bug que não consigo reproduzir?

Diga se aconteceu uma vez ou de forma intermitente, registre o que observou e o ambiente que conhece, e informe quais tentativas não conseguiram reproduzi-lo. Não preencha etapas desconhecidas com palpites.

Devo anexar registros a uma issue pública?

Somente depois de verificar se contêm informações secretas e pessoais. Remova ou oculte dados sensíveis e compartilhe apenas o menor trecho que ajude a explicar a falha. Siga as regras de incidentes e privacidade da sua equipe.

Baixe o Talkpad grátis – 2.500 palavras por semana no plano gratuito.