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:
Estudos de caso publicados. Consulte 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 pull para a documentação de integração demoram muito para ser 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 causa e efeito. O que pode estar causando o problema que você descreveu? Lembre-se de que 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 ficam retornando para os colaboradores sobre a formatação."
  • "Os usuários precisam abrir 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 e tempos limite do plano do provedor."
  • "As pessoas ficam mal-humoradas nas nossas reuniões semanais porque elas são à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 precisam discutir sobre formatação, tom e estilo."
  • "Se tivéssemos documentação sobre códigos de erro, os usuários poderiam encontrar as respostas lá, em vez de abrir problemas."
  • "Hmm, parece que uma documentação melhor não resolveria nosso problema de CI/CD."
  • "Podemos começar cada reunião com uma piada de knock-knock! Criar uma coleção de piadas de knock-knock nos ajudaria a começar nossas reuniões com um sorriso."

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 desistir?"
  • "Quantos problemas relacionados a códigos de erro são "muitos problemas"?"
  • "Hmmm… o que significa 'muito 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 quanto tempo um pull request está aberto e quanto tempo se passou 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 pesquisar o texto do código de erro nos problemas."
  • "Não podemos medir a irritação das pessoas de maneira tática ou precisa."

Adicionar uma métrica secundária

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

  • "As RPs mais longas levam mais tempo para serem analisadas. Devemos ter limites diferentes para tamanhos diferentes de RPs. Queremos medir o tempo de mesclagem para PRs pequenas, médias, grandes e gigantescas."
  • "Podemos verificar quantas visitas a documentação do código de erro recebe e ver 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 a 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 alcançássemos nossa meta de fechar todos os novos RPs em menos de um mês, isso seria um sucesso. Se o tempo médio para fechar PRs grandes diminuísse duas semanas, seria um grande sucesso."
  • "Idealmente, não haveria novos problemas relacionados a erros. Mas consideraria nosso projeto um sucesso se houvesse uma redução de 50% nos problemas relacionados a erros abertos."