Como escolher as métricas certas para seu projeto

Este guia destina-se a ajudar as organizações a entender que tipos de problemas podem ser resolvidos por uma documentação melhor e como escolher métricas apropriadas para projetos de documentação.

Fase atual:
O programa "Season of Docs" de 2021 terminou em 14 de dezembro de 2021. Consulte linha do tempo.

Relate seu 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 pouco 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? Os problemas podem ter várias causas ou causas sobrepostas.

  • "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 desistem da revisão do RP porque não sabem o que fazer ou conversam com os colaboradores sobre 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 do plano e tempos limite do nosso 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 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."
  • "Hmm, não parece que uma documentação melhor resolveria nosso problema de CI/CD."
  • "Podemos começar cada reunião com uma piada! 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 'demorar muito para combinar RPs'? 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"?"
  • "Hmmm… como é "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 quantas questões estão marcadas como "código de erro" ou pesquisar o texto do código de erro nas questões."
  • "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? A 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 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 poderíamos considerar nosso projeto bem-sucedido se tivéssemos um declínio de 50% nas questões relacionadas a erros abertas.”