Como escolher as métricas certas para seu projeto

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

Fase atual:
Os resultados foram anunciados. Consulte a linha do tempo.

Descreva o problema

Antes de escolher uma métrica, entenda bem o problema que você 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 serem mescladas. Os colaboradores desistem e vão embora.”
  • "Há 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 por causa e efeito. O que pode estar causando o problema que você descreveu? Os problemas podem ter várias causas ou causas sobrepostas.

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

Propor uma solução

Esse problema pode ser resolvido com uma documentação nova ou melhor?

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

Seja específico

Você pode quantificar o problema?

  • "O que significa "leva muito tempo para mesclar as solicitações de fusão"? Dois meses? Duas semanas? Quanto tempo os colaboradores vão esperar pela revisão antes de desistirem?
  • "Quantos problemas relacionados a códigos de erro são "muitos problemas"?"
  • "Humm... quão mal-humorado é?"

Verificar a mensurabilidade

Como você verificaria a métrica proposta? É possível medir de forma fácil e precisa? A medição depende de quem está fazendo a medição?

  • "Podemos medir facilmente há quanto tempo uma solicitação de envio está aberta e há quanto tempo desde que uma análise foi solicitada. Não podemos medir exatamente quando um colaborador desiste.”
  • "Podemos contar quantos problemas estão marcados como 'código de erro' ou procurar o texto do código do erro em problemas".
  • "Não podemos medir a irritação das pessoas de uma forma educada ou precisa."

Adicionar uma métrica secundária

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

  • “RPs mais longos levam mais tempo para serem analisados; devemos ter limites diferentes para tamanhos distintos de PRs. Queremos medir o tempo de mesclagem para PRs pequenos, médios, grandes e gigantescos.”
  • "Podemos verificar quantas visitas a documentação do código de erro recebe e verificar se esse número está relacionado a menos problemas abertos."

Escolha um período

  • "Achamos que duas semanas é um tempo razoável para mesclar PRs pequenas e médias. Todas as PRs precisam ser mescladas em um mês. Então vamos medir a cada duas semanas."
  • "Não faz sentido atualizar o número de problemas relacionados a códigos de erro diariamente, porque nosso tempo típico para fechar um problema é de uma semana. Vamos medir isso semanalmente."

Definir 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 atingimos nossa meta de fechar todos os novos RPs em menos de um mês, isso seria um sucesso. Se nosso tempo médio para fechar grandes RPs diminuísse em duas semanas, isso seria um grande sucesso."
  • “Idealmente, não haveria novos problemas relacionados a erros. Mas consideraremos nosso projeto um sucesso se houver uma redução de 50% nos problemas relacionados a erros abertos."