Fonte: Unsplash

Como documentar bugs de forma simples e clara

Diminua pela metade o tempo para correção de problemas.

Olá, eu sou a Jess, mais uma sobrevivente no universo gestão de produto e tecnologia. Quero compartilhar o que por muito tempo foi uma grande fraqueza minha: reportar um bug. Minha maior dificuldade era saber como repassar o problema de um jeito que o time de desenvolvimento conseguisse ler e já identificar o que precisava ser corrigido e onde no código deveria atuar. Acontece que apenas dizer que “há um erro em tal tela” não é o suficiente para entender o que está acontecendo, nem mesmo encontrar a causa do problema.

Levei tempo até chegar em um modelo de documentação clara o bastante. Cada vez que eu reportava um bug, voltavam muitas dúvidas e questionamentos sobre ele. E por mais que eu tentasse colocar todo tipo de informação que eu achasse ter relação, continuavam perguntando. Mas graças a essas interrogações eu pude aprender aos poucos o que faz sentido relatar e cheguei em um modelo que funciona muito bem com meu time. Veja se também faz sentido para você.

Conseguir reproduzir é 80% da solução

Constatei que quando o bug chegava nas mãos do time de desenvolvimento, eles passavam a maior parte do tempo tentando reproduzir aquele erro, ou seja, replicavam os passos realizados pelo usuário até chegar no erro. Dizer que “dá erro quando eu coloco um item no carrinho” pode ser consequência de uma infinidade de cenários: pode estar faltando algum dado, o item pode estar indisponível, a versão do app pode estar com problema. Quanto maior e mais complexo o produto, maiores são as possibilidades e combinações de barreiras que o usuário pode encontrar. O fato é que só saberemos identificar a causa do pepino se repetirmos o caminho percorrido. Logo, se eu pudesse inserir essa reprodução na documentação do bug, o time de desenvolvimento teria mais tempo para descobrir a causa e corrigir.

Modelo essencial de Bug Report

Diferente do que eu acreditava, abarrotar a documentação de informações não necessariamente ajudava na solução. Mas sim compreender o fundamental para detectar o código que deve ser corrigido e colocar esses dados em uma ordem que passe uma mensagem compreensível. Nesse caso, o modelo mais eficaz que chegamos é o seguinte:

1. Problema/contexto

Comece dizendo qual o problema como se fosse contar uma fofoca enquanto toma um café, bem simples e direto. Não deve passar de duas a três frases. Nessa mensagem o receptor deve compreender o que não está funcionando direito e a consequência disso para o usuário ou produto. Se já tiver alguma sugestão do que pode ser o causador do problema, é uma boa sinalizar.

Exemplo
“Os usuários não estão conseguindo selecionar a quantidade de itens e isso afeta na conclusão da compra”.

2. Como reproduzir

Recrie os passos que levaram ao erro. Liste a sequência de ações feitas no produto, indicando o que foi clicado, o que apareceu, telas envolvidas e mensagens recebidas. Anexe uma evidência, ou seja, um vídeo reproduzindo o caminho ou fotos de cada etapa.

Parece fácil, mas muitas vezes não conseguimos repetir esses passos e chegar no erro direto, porque pode ser que o problema seja nas particularidades do contexto do usuário. Nesse caso, você pode pedir para o próprio usuário enviar a evidência, ou para outros membros do time testarem. Garanto que para a maior parte dos problemas você terá uma reprodução de sucesso somente com essas alternativas, mas se ainda não conseguir, tente analisar o histórico (logs) desse usuário.

Haverão ocorrências que, apesar das tentativas, serão bem penosas de simular. Nessas horas você pode envolver outros departamentos para ajudar ou considerar esperar ter outros episódios similares para conseguir comparar e perceber algum padrão. Todavia, não vale a pena passar para o time de desenvolvimento enquanto essa parte da investigação não for concluída, visto que as chances de correção do problema são bem pequenas.

Exemplo
- Acessei o site através do link dessa campanha;
- entrei na tela do produto;
- o botão de comprar estava desabilitado e na tela indicava que eu precisava selecionar uma quantidade de itens;
- cliquei no botão “1 quantidade”, mas o botão de comprar continuou desabilitado.

3. Impacto percebido

Mencione o espectro de pessoas impactadas com o problema, isso ajuda tanto na investigação, quanto na priorização. Em muitos casos você pode não ter precisão dessa informação, mas tudo bem, compartilhe o que conseguir identificar.

Dados que demonstram o impacto: plataformas que apresentaram o erro, versão do aplicativo, se ocorreu com usuários com conta ou também visitantes, período de tempo em que se percebeu o problema, produtos envolvidos, quantidade de atendimento gerado, etc.

Enquanto estiver reproduzindo o erro, aproveite para testar outras combinações e assegurar que o problema só existe naquele cenário, por exemplo, se o problema acontece só no app ou também na web.

Exemplo
Usuários que selecionaram 1 ou 2 quantidades, estando logados ou não. Verificamos que no app está correto

4. Comportamento esperado

Por fim, deixe claro o que deveria ser o comportamento correto. Parece óbvio para você, mas pode não ser para quem está corrigindo. E seja objetivo, assim como na descrição do problema. Não tenha receio de ser repetitivo, isso ajuda a reforçar o resultado que você espera.

Exemplo
Ao selecionar as quantidades 1 ou 2 no checkout, deve habilitar o botão de compra e ser possível concluir.

Fonte: Autor

Informações complementares

Sabendo que este é um modelo essencial, ou seja, que contém as principais informações e não todas possíveis, você pode complementar de acordo com as necessidades e organização do seu time. As mais comuns são: quem reportou o bug; quando foi reportado; a prioridade para correção; tecnologias envolvidas; dados sobre o impacto; entre outros.

Se você gostou desse artigo, peço retribuições:

1. Respeite a todos, mas principalmente as mulheres e a natureza.
2. Se você evoluir esse modelo, compartilhe comigo!

Beijos em seus corações.