Como escolher as métricas certas para seu projeto

Este guia tem como objetivo ajudar as organizações a entender quais tipos de problemas podem ser resolvidos com uma documentação melhor e como escolher métricas apropriadas para projetos de documentação.

Fase atual:
Resultados anunciados da linha do tempo.

Indique o problema

Antes de começar a escolher uma métrica, você precisa entender bem o problema que está tentando resolver. Forneça a resposta mais específica possível.

  • "As solicitações de envio da nossa documentação de integração levam muito tempo para serem mescladas. Os colaboradores desistem e desaparecem.”
  • "Identificamos muitos problemas abertos para ajudar a entender os códigos de erro."
  • "Nosso pipeline de CI/CD é instável. Muitos testes falham por motivos mal compreendidos.”
  • "As pessoas parecem mal-humoradas nas nossas reuniões semanais."

Desenvolver uma hipótese

Procure causa e efeito. Qual pode ser a causa do problema que você afirmou? Tenha em mente que os problemas podem ter várias causas ou conflitos sobrepostos.

  • "Leva muito tempo para mesclar as solicitações de envio da documentação de integração, porque não temos orientações claras sobre o estilo. Os revisores atrasam a revisão do RP porque não sabem o que fazer ou recorrem aos colaboradores sobre a formatação."
  • "Os usuários precisam abrir os problemas porque não conseguem encontrar informações sobre códigos de erro na documentação."
  • "Nossos testes de CI/CD falham porque nosso provedor atingiu as limitações de plano e os tempos limite."
  • "As pessoas ficam mal-humoradas nas nossas reuniões semanais porque elas são às 5h30 no fuso horário deles."

Propor uma solução

Esse é um problema que poderia ser resolvido com uma documentação nova ou melhor?

  • "Se tivéssemos um guia de estilo, os participantes poderiam verificá-lo antes de enviar as PRs. Os revisores saberiam o que verificar. Os revisores e colaboradores não precisam discutir sobre formatação, tom e estilo."
  • "Se tivéssemos documentação sobre código de erro, os usuários conseguiriam encontrar as respostas lá em vez de abrir problemas."
  • “Hmm, parece que uma documentação melhor não resolveria nosso problema de CI/CD.”
  • "Poderíamos começar cada reunião com uma piada sobre toc toc! Criar uma coleção de piadas tipo toc-toc nos ajudaria a começar nossas reuniões com um sorriso."

Dê informações específicas

Você consegue quantificar o problema?

  • "O que 'demora muito para mesclar RPs' realmente significa? Dois meses? Duas semanas? Quanto tempo os colaboradores vão esperar pela revisão antes de desistir?”
  • "Quantos problemas relacionados a código de erro são 'muitos problemas'?"
  • "Hmm... como mal-humorado é 'muito mal-humorado'?"

Verificar mensurabilidade

Como você verificaria a métrica proposta? Ela pode ser medida de maneira fácil e precisa? A medição depende de quem está medindo?

  • "Podemos medir facilmente há quanto tempo uma solicitação de envio está aberta e há quanto tempo uma revisão foi solicitada. Não podemos medir exatamente quando um colaborador desiste.”
  • "Podemos contar quantos problemas foram marcados com 'código de erro' ou procurar o texto do código de erro dentro dos problemas."
  • "Não podemos medir o mal-humorado das pessoas de uma forma tática ou precisa."

Adicionar uma métrica secundária

Existem outras métricas que ajudariam você a entender se sua documentação está resolvendo seu problema? Sua métrica desejada é a mesma em todos os casos?

  • "Os PRs mais longos levam mais tempo para revisar. Devemos ter limites diferentes para diferentes tamanhos de PRs. Queremos medir o tempo de mesclagem de PRs pequenos, médios, grandes e gigantes."
  • "Podemos verificar quantas visitas nossa documentação de código de erro recebe e ver se esse número está relacionado a menos problemas abertos."

Escolha um período

  • "Acreditamos que duas semanas é um tempo razoável para mesclar PRs de pequeno a médio e médio, e todos os PRs devem ser mesclados dentro de um mês. Portanto, faremos a medição a cada duas semanas."
  • "Não faz sentido atualizar o número de problemas relacionados a códigos de erro diariamente, porque o tempo médio para resolver um problema é de uma semana. Vamos medir semanalmente."

Defina metas.

Quanta mudança você precisa ver na métrica selecionada para dizer que o projeto foi um sucesso? Considere definir metas quantitativas para as métricas que você escolheu.

  • "Se atingíssemos nossa meta de encerrar a cada novo RP em menos de um mês, isso seria um sucesso. Se nosso tempo médio para fechar PRs grandes diminuíssem em duas semanas, isso seria um grande sucesso."
  • "O ideal é que não haja novos problemas relacionados a erros. Mas poderíamos considerar nosso projeto bem-sucedido se houvesse uma queda de 50% nas questões relacionadas a erros."