Como escolher as métricas certas para seu projeto

Este guia destina-se a 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:
desenvolvimento da documentação. Consulte o cronograma.

Indique seu 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 demoram muito para ser mescladas. Colaboradores desistem e vão embora."
  • "Vemos muitos problemas abertos para ajudar a entender os códigos de erro."
  • "Nosso pipeline de CI/CD é instável. Muitos testes falham por motivos pouco compreendidos."
  • "As pessoas parecem mal-humoradas nas nossas reuniões semanais."

Desenvolver uma hipótese

Procure por causa e efeito. Qual poderia ser a causa do problema que você afirmou? Lembre-se de que os problemas podem ter várias causas ou se sobrepõem.

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

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 confirmadores poderiam verificá-lo antes de enviar seus PRs. Os revisores saberiam o que verificar. Os revisores e colaboradores não precisariam discutir sobre formatação, tom e estilo."
  • "Se tivéssemos a documentação do código do erro, os usuários poderiam encontrar as respostas lá, em vez de abrir os problemas."
  • "Hmm, não parece que uma documentação melhor resolveria nosso problema de CI/CD."
  • "Podemos começar cada reunião com uma piada toc-toc! Criar uma coleção de piadas toc-to nos ajudaria a iniciar nossas reuniões com um sorriso."

Seja específico

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 análise antes de desistir?"
  • "Quantos problemas relacionados ao código de erro são 'muitos problemas'?"
  • "Hmm... como você está 'muito mal-humorada'?"

Verificar mensurabilidade

Como você verificaria a métrica proposta? Pode ser medido com facilidade e precisão? A medição depende de quem está fazendo a medição?

  • "Podemos medir facilmente por 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 como 'código de erro' ou pesquisar o texto do código de erro nos problemas."
  • "Não podemos medir o mal-humorado das pessoas de maneira 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. Precisamos ter limites diferentes para tamanhos diferentes de PRs. Queremos medir o tempo de mesclagem para 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 porte, e todos os PRs devem ser combinados em um mês. Então, vamos fazer a medição a cada duas semanas."
  • "Não faz sentido atualizar o número de problemas relacionados ao código de erro diariamente, porque nosso tempo normal para encerrar um problema é de uma semana. Nós vamos fazer isso semanalmente."

Defina metas.

Quanta mudança você precisaria ver na métrica selecionada para dizer que o projeto foi um sucesso? Defina metas quantitativas para as métricas escolhidas.

  • "Se atingíssemos nossa meta de fechar todos os novos RP em menos de um mês, isso seria um sucesso. Se nosso tempo médio para fechar PRs importantes diminuísse em duas semanas, isso seria um grande sucesso."
  • "Idealmente, não veríamos novos problemas relacionados a erros. Mas consideraríamos nosso projeto bem-sucedido se observássemos um declínio de 50% nos problemas relacionados a erros abertos.”