Como Obter um Relatório de Bug Utilizável de Alguém Que Não É Técnico

Quem não é técnico não faz piores relatórios. Está a responder a uma pergunta diferente da que fez, e geralmente o problema era a própria pergunta.

Quase todos os formulários de relatório de bug pedem as mesmas três coisas: o que deu errado, os passos para reproduzir, e o que deveria ter acontecido. Cada um pede ao utilizador que faça um diagnóstico. “O que deu errado” pede uma causa. “Esperado versus real” pede-lhe que saiba o que o software deveria fazer, que é o conhecimento que não têm e a razão pela qual o contactam. “Passos para reproduzir” pede que estivessem atentos a uma sequência que não merecia atenção até falhar.

O que alguém pode dar-lhe com precisão é o que estava a tentar fazer e o que viu. Essas são observações. A maioria do resto do formulário é um pedido de uma teoria.

A teoria é a parte a deixar de lado

O que mais custa num relatório não treinado não é o detalhe em falta. É a explicação, porque uma explicação chega parecendo uma observação e vai passar a manhã dentro dela.

“Desconectou-me” é uma conclusão. Por baixo dela, o que realmente aconteceu é que apareceu um ecrã com um formulário de início de sessão. Esse ecrã tem pelo menos quatro causas que não têm nada a ver uma com a outra: a sessão expirou mesmo, uma chamada de API devolveu um 401 e o cliente redirecionou, uma página em cache foi servida com o cabeçalho de desconexão, ou tinham um segundo separador aberto e desconectaram nesse. Começar de “desconectou-me” e vai para o armazenamento de sessão. Começar de “um ecrã de início de sessão apareceu enquanto estava no pagamento” e tem o timing, a página e o sintoma, e o armazenamento de sessão é um de quatro locais para procurar em vez de ser o único.

Fraco

O site desconectou-me enquanto estava a pagar.

Melhor

Estava no passo de pagamento e o ecrã voltou ao formulário de início de sessão. O meu carrinho estava ainda lá depois.

Nada na versão melhor requer conhecimento técnico. É a mesma pessoa, pedida pelo que viu em vez do que significava.

Palavras que não significam o que assume

O vocabulário é partilhado e as definições não são. Estas cinco fazem mais dano porque ambos os lados têm a certeza que compreenderam uma à outra.

Falhou

O separador fechou, a página ficou em branco, um spinner nunca parou, ou o navegador em si fechou.

Congelou

Nada respondeu a cliques, ou algo estava a carregar sem indicação de que estava.

Apagou

Desapareceu da lista à sua frente. Pode estar filtrado, noutra página, noutra conta, ou realmente apagado.

Página

Um URL, um separador, um modal, um passo num fluxo, ou o site todo.

Erro

Uma mensagem que escreveu, um ecrã de erro do navegador, ou simplesmente um resultado que não queriam.

Não pode corrigir isto publicando um glossário, porque ninguém lê um antes de reportar um problema. Corrige isto nunca fazendo uma pergunta cuja resposta seja uma destas palavras. “Falhou?” não tem nenhuma resposta útil. “O que estava no ecrã quando parou de funcionar?” tem.

Pergunte sobre a última coisa que funcionou

A pergunta mais produtiva para colocar a alguém sem o vocabulário não é sobre a falha de todo.

Pergunte o que estava a fazer imediatamente antes, e pergunte se já funcionou. Ambos são coisas que uma pessoa se lembra sem esforço, e entre elas vinculam o problema: o primeiro dá-lhe o ponto de entrada, e o segundo diz-lhe se está a procurar uma regressão ou algo que nunca funcionou para esta pessoa nesta situação. Uma funcionalidade que funcionou para eles na terça passada e não hoje é uma investigação diferente daquela que nunca viram funcionar.

“Já funcionou para si?” também faz algo que as outras perguntas não fazem. É respondível com um sim ou um não, por isso quase sempre é respondido.

Peça o ecrã, não uma descrição

Uma captura de ecrã é o artefato que alguém não treinado produz de forma fiável e precisa, porque fazer uma não precisa de vocabulário de todo. Leva coisas que não teriam podido dizer se perguntasse: o URL na barra de endereço, a largura da janela, qual conta está conectada, a exatidão da mensagem, se um banner estava a cobrir o botão. A maioria do que teria extraído em quatro e-mails está numa imagem que levou cinco segundos.

Portanto “poderia enviar-me uma imagem do que está a ver” vale mais que qualquer pergunta que pudesse escrever, e é a coisa mais fácil da lista para pedir.

O limite vale a pena saber também. Uma captura de ecrã mostra a superfície num momento. Não pode dizer o que o navegador estava a fazer por baixo, e a falha muitas vezes não deixa marca na superfície: um pedido que devolveu um 500 enquanto a página parecia normal é invisível numa imagem.

O que não podem dar-lhe, e não deveria pedir

Erros de consola, o registo de rede, a versão do navegador, o tamanho da viewport. Estas são as coisas que realmente encurtariam a investigação, e cada uma delas requer ao utilizador que abra um desenvolvedor e saiba o que procurar.

Pedir por elas tem um custo real e não é o tempo do utilizador. É que o pedido lê como um teste. Alguém que não consegue encontrar a consola agora sabe que falhou em ajudar adequadamente, e a próxima coisa que notam eles mantêm para si. A oferta de pessoas dispostas a contar-lhe sobre um problema é pequena e inteiramente voluntária, e é mais fácil de perder do que de construir.

A resposta honesta é que esta metade deveria ser recolhida em vez de pedida.

Não escreverá o título para si, e não pode dizer-lhe o que a pessoa estava a tentar fazer. Essa parte só vem de perguntar, o que é porque as perguntas importam.

Pergunte um de cada vez

Uma lista de seis perguntas volta com duas respostas e nenhuma indicação de quais quatro foram saltadas. Pior, lê como um formulário, e um formulário é uma coisa que as pessoas adiam até ao fim de semana.

Envie uma pergunta. Quando é respondida, envie a próxima se ainda precisar. Parece mais lento e não é, porque a alternativa é um longo silêncio seguido de uma resposta parcial que gera mais três perguntas mesmo assim.

Tenha em mente o que está a interromper. Um relatório de bug é o fim de uma cadeia de pequenas decisões de incômodo: notaram, decidiram que não era culpa deles, descobriram onde contar-lhe, e escreveram. Cada troca depois disso é outra chance para a cadeia quebrar, e nada lhe diz quando o faz. Só nunca ouve falar novamente, que do seu lado é indistinguível do problema ter desaparecido.

As perguntas, na ordem para as fazer

Quatro perguntas, nenhuma das quais requer que a pessoa saiba algo sobre software:

• O que estava a tentar fazer?
• O que viu em vez disso? Se puder, envie uma imagem disso.
• Quando foi isto, aproximadamente, e o que estava a usar nessa altura?
• Já funcionou para si antes?

Se obter essas quatro, tem o ponto de entrada, o sintoma, um período para procurar nos seus registos, e se é uma regressão. Isso é suficiente para começar, e é mais do que a maioria dos bilhetes escritos por pessoas que conhecem o vocabulário.