Na primeira parte do relatório, descrevemos como medir a qualidade da documentação e a eficácia de seu desenvolvimento. Agora mergulhe nos detalhes da contagem de métricas.
Diz Yuri Nikulin, chefe do serviço de desenvolvimento de documentação técnica.
Para começar, vamos definir o que é desempenho. No sentido clássico, esse é o tempo necessário para produzir uma unidade de produção ou a quantidade de produção produzida por unidade de tempo .
Por exemplo, esse é o número de telefones produzidos por mês ou o tempo necessário para produzir milhares de telefones. Surge a questão de como medir o trabalho intelectual em que nosso departamento está envolvido.
Se aplicarmos a abordagem clássica para avaliar a produtividade, podemos calcular quantos documentos, páginas ou palavras são escritos por dia, semana e mês. Isso ajudará a estimar o tempo potencial para a produção de documentação no futuro, mas não responderá à pergunta sobre produtividade. Afinal, definitivamente não estamos interessados em avaliar a eficácia dos escritores pelo número de palavras escritas por eles. Portanto, decidimos que deveríamos começar com os requisitos para as métricas que planejamos contar.
Identificamos vários critérios para selecionar métricas:
- Transparência A abordagem para calcular métricas e interpretar os resultados deve ser clara não apenas para nós, mas também para os clientes.
- Disponibilidade de dados. Incluindo dados de qualquer período passado, a fim de apresentar hipóteses e tentar confirmá-las com dados históricos.
- Capacidade de automatizar a contagem. Definitivamente, não queremos contar métricas manualmente.
Como resultado, percebemos que o objeto ideal para calcular métricas de desempenho é a tarefa no Tracker. Ele atende a todos os requisitos que definimos para métricas.
A fonte de dados para nós era o Yandex.Tracker. É bastante flexível e facilmente personalizável para nossas tarefas. Ele já possui todos os dados necessários, porque usamos essa ferramenta todos os dias. E o Tracker também possui uma API, o que significa que você pode usar essas informações e automatizar processos.
Então, tínhamos um plano de como proceder.
Configurar filas e tarefas
Você precisa começar escolhendo as filas, a hierarquia de tarefas, seus tipos e status.
Isso foi descrito em detalhes por Katya Kunenko no relatório " Ferramentas para a preparação da documentação do usuário ". Falaremos brevemente sobre filas e tarefas, que usamos a nós mesmos.
Filas
Temos três linhas, que em essência refletem nosso público-alvo.
Hierarquia de tarefas
Nossas tarefas têm uma estrutura de dois níveis:
- no nível superior, as tarefas correspondem a documentos publicados,
- no nível inferior, as tarefas correspondem ao trabalho no documento.
Tipos e status de tarefas
Os tipos e status de tarefas não apenas permitem classificar os tipos de trabalho e seu estado atual, mas também consideram nossas métricas com seções.
Linha do tempo para concluir tarefas. A linha azul é o tempo médio de produção do documento, a laranja é o tempo para corrigir o erro, o verde é o tempo médio para concluir tarefas de todos os tipos.
Vamos contar um exemplo de gráfico. Por exemplo, um bug é corrigido dentro de 1 a 5 dias e leva de 30 a 40 para escrever um novo documento. Ao mesmo tempo, escrevemos novos documentos com menos frequência do que complementamos os antigos ou corrigimos erros. Portanto, o tempo médio de execução de uma tarefa de qualquer tipo (linha verde) é muito longo para erros e muito curto para novos documentos. Com sua ajuda, temos apenas uma idéia média da velocidade de resolução de problemas.
Como consideramos as métricas para otimizar processos, precisamos examinar fatias mais precisas: por exemplo, quanto tempo resolvemos o problema de "bug" ou "novo documento". E a média de todos os tipos pode ser visualizada para acompanhar a tendência geral.
Usamos esse tipo de conjunto de tarefas.
Existem mais status do que tipos, porque o fluxo de trabalho exige isso.
É mais fácil trabalhar com tipos e status se eles não forem ambíguos e não houver muitos deles. Caso contrário, os artistas podem ficar confusos.
Como considerar métricas de desempenho
Na última parte, dissemos que realizamos um estudo e selecionamos 20 métricas de documentação dentre 136. Seis delas são métricas de desempenho.
Existem dois aspectos na contagem de métricas.
- Contando métricas fatiadas. Acima, dissemos o que é e por que é importante para nós.
- Contando valores médios.
A abordagem clássica de calcular valores médios é resumir todos os indicadores e dividir por seu número. Essa abordagem nem sempre funciona bem porque leva em consideração casos degenerados. Por exemplo, sabemos que a maioria dos erros corrigidos em um dia. Mas há casos degenerados - por exemplo, um ticket é perdido ou um funcionário sai - então leva mais tempo para consertá-lo. Suponha que tenhamos seis bugs para o período em análise. Decidimos cinco em um dia e um em 115. Acontece que a correção média de bug é de 20 dias. Mas esse número não reflete a realidade: quase sempre corrigimos erros do dia, e um ticket longo afeta significativamente esse indicador.
Nesses casos, o percentil chega ao resgate. Esse é o valor máximo (no nosso caso, métricas), que se ajusta à porcentagem especificada de objetos. Por exemplo, o percentil 80 é um valor que não excede 80% dos objetos na amostra. No nosso caso, esse valor seria 1, pois 83% dos objetos não o excedem.
Aqui o terceiro plano aparece - o tempo em que contamos as métricas. Quase todas as nossas métricas contam em 30 dias.
Consideramos métricas com cortes da seguinte forma:
- primeiro todas as linhas juntas,
- então cortamos em turnos
- depois detalhamos: fazemos um corte nas filas com um corte para todos os tipos de tarefas.
Cada seção subsequente da métrica refina a anterior. O valor médio para todas as filas, tipos e status de tarefas fornece uma ideia generalizada. Em seguida, consideramos o valor das filas individuais para entender como estão as coisas com a documentação técnica, do usuário ou interna. No último nível, mais detalhado, estamos trabalhando na linha "fila + tipo e status".
Além disso, mostraremos como consideramos as métricas de desempenho.
Número de tarefas fechadas
Como consideramos: de acordo com o número de tarefas que estão fechadas no intervalo [31 dias atrás; ontem].
O número de tarefas realizadas no trabalho
Como consideramos: de acordo com o número de tarefas para as quais o início do trabalho está no intervalo [31 dias atrás; ontem].
O número de dias antes da contratação
Como consideramos:
- Para cada tarefa que foi levada para trabalhar no período especificado (data de início no Rastreador no intervalo [31 dias atrás; ontem]), consideramos o número de dias completos decorridos entre a declaração (data de criação do campo) e o início da tarefa (data de início do campo) .
- Resumimos todos os valores obtidos na primeira etapa.
- Dividimos o valor recebido pelo número de tarefas para as quais realizamos o primeiro item.
Para percentis, o item 3 é omitido, os valores são classificados em ordem crescente e o valor que corresponde ao percentil especificado é selecionado.
Número de dias para concluir
Como consideramos.
- Para cada tarefa que foi concluída no período especificado (data de término no Rastreador no intervalo [31 dias atrás; ontem]), consideramos o número de dias completos decorridos entre o início do trabalho (data de início do campo) e a tarefa (data de término do campo).
- Resumimos todos os valores obtidos na primeira etapa.
- Dividimos o valor recebido pelo número de tarefas para as quais realizamos o primeiro item.
Para percentis, o item 3 é omitido, os valores são classificados em ordem crescente e o valor que corresponde ao percentil especificado é selecionado.
O número de tarefas sem reação por mais de 14 dias
Como acreditamos: pelo número de tarefas em que nada aconteceu por mais de 14 dias. É determinado pelo campo atualizado no Rastreador: o valor do campo deve ser menor que "ontem - 14 dias".
Dívida técnica
Como consideramos: pelo número de tarefas para as quais o status da lista de pendências é definido no rastreador.
Implementação técnica de cálculo de métricas de desempenho
No nível superior, o sistema de contagem métrica consiste nos seguintes componentes e links de informações.
Programa de contagem métrica programada
Usamos o Nirvana , uma plataforma de computação universal. Descreve formalmente a ordem na qual os processos são iniciados. Juntamente com o planejador interno (planejador), o Nirvana nos substitui por um conjunto de scripts bash e cron.
Um programa escrito em Python é executado regularmente e solicita os dados necessários para o cálculo de métricas.
Sistema de configuração de tarefas
Os dados para o cálculo de métricas no nosso caso são armazenados no Yandex.Tracker. Como uma interface para os dados, usamos a API Yandex.Tracker Python - este é um invólucro na API HTTP, que permite mais rápido e fácil receber informações em estruturas de dados adequadas para processamento adicional.
Você pode escolher um sistema conveniente com uma API adequada, por exemplo, Jira.
Sistema de preparação de gráficos
Após calcular as métricas com base nos dados do Yandex.Tracker, nosso programa gera arquivos JSON e os transfere para o serviço interno do Yandex.Statistics para desenhar gráficos.
Você pode usar algum tipo de biblioteca JS que pode construir gráficos. Uma visão geral de algumas soluções semelhantes está em Habré:
15 melhores bibliotecas JavaScript
Na próxima parte, descreveremos como consideramos as métricas de qualidade da documentação do usuário.