Dans la première partie du rapport, nous avons décrit comment mesurer la qualité de la documentation et l'efficacité de son élaboration. Plongez maintenant dans les détails du comptage des métriques.
Dit Yuri Nikulin, chef du service de développement de la documentation technique.
Pour commencer, définissons ce que sont les performances. Au sens classique, il s'agit du temps nécessaire pour produire une unité de production ou la quantité de production produite par unité de temps .
Par exemple, il s'agit du nombre de téléphones produits par mois ou du temps nécessaire pour produire des milliers de téléphones. La question se pose de savoir comment mesurer le travail intellectuel dans lequel notre service est engagé.
Si nous appliquons l'approche classique à l'évaluation de la productivité, nous pouvons calculer le nombre de documents, pages ou mots écrits par jour, semaine et mois. Cela aidera à estimer le temps potentiel pour produire de la documentation à l'avenir, mais ne répondra pas à la question sur la productivité. Après tout, nous ne sommes certainement pas intéressés à évaluer l'efficacité des écrivains par le nombre de mots écrits par eux. Par conséquent, nous avons décidé de commencer par les exigences relatives aux mesures que nous avions prévu de compter.
Nous avons identifié plusieurs critères de sélection des métriques:
- La transparence L'approche du calcul des métriques et de l'interprétation des résultats doit être claire non seulement pour nous, mais aussi pour les clients.
- Disponibilité des données. Y compris les données de toute période passée afin de proposer des hypothèses et essayer de les confirmer avec des données historiques.
- Capacité d'automatiser le comptage. Nous ne voulons certainement pas compter les statistiques à la main.
En conséquence, nous avons réalisé que l'objet idéal pour calculer les mesures de performance est la tâche dans le Tracker. Il répond à toutes les exigences que nous avons définies pour les métriques.
La source de données pour nous était Yandex.Tracker. Il est assez flexible et facilement personnalisable pour nos tâches. Il possède déjà toutes les données nécessaires, car nous utilisons cet outil tous les jours. Et le Tracker dispose également d'une API, ce qui signifie que vous pouvez utiliser ces informations et automatiser les processus.
Nous avions donc un plan pour procéder.
Configurer des files d'attente et des tâches
Vous devez commencer par choisir les files d'attente, la hiérarchie des tâches, leurs types et statuts.
Cela a été décrit en détail par Katya Kunenko dans le rapport « Outils pour la préparation de la documentation utilisateur ». Nous parlerons brièvement des files d'attente et des tâches que nous utilisons nous-mêmes.
Files d'attente
Nous avons trois lignes, qui reflètent essentiellement notre public cible.
Hiérarchie des tâches
Nos tâches ont une structure à deux niveaux:
- au plus haut niveau, les tâches correspondent aux documents publiés,
- au niveau inférieur, les tâches correspondent au travail sur le document.
Types et statuts des tâches
Les types et les statuts des tâches nous permettent non seulement de classer les types de travail et leur état actuel, mais également de considérer nos métriques avec des sections.
Calendrier de réalisation des tâches. La ligne bleue est le temps de production moyen du document, l'orange est le temps de corriger le bogue, le vert est le temps moyen pour terminer les tâches de tous types.
Nous raconterons sur un exemple de graphe. Par exemple, un bogue est corrigé dans un délai de 1 à 5 jours et il faut 30 à 40 pour écrire un nouveau document. En même temps, nous rédigeons de nouveaux documents moins souvent que nous complétons les anciens ou corrigeons des erreurs. Par conséquent, le temps d'exécution moyen d'une tâche de tout type (ligne verte) est trop long pour les bogues et trop court pour les nouveaux documents. Avec son aide, nous n'avons qu'une idée moyenne de la vitesse de résolution des problèmes.
Étant donné que nous considérons les mesures afin d'optimiser les processus, nous devons examiner des tranches plus précises: par exemple, combien de temps nous résolvons le problème du «bogue» ou du «nouveau document». Et la moyenne pour tous les types peut être consultée pour suivre la tendance générale.
Nous utilisons un tel ensemble de types de tâches.
Il existe plus de statuts que de types, car le workflow l'exige.
Il est plus facile de travailler avec des types et des statuts s'ils ne sont pas ambigus et qu'ils ne sont pas trop nombreux. Sinon, les interprètes peuvent devenir confus.
Comment considérer les mesures de performance
Dans la dernière partie, nous avons dit que nous avons mené une étude et sélectionné 20 mesures de documentation sur 136. Six d'entre elles sont des mesures de performance.
Le comptage des métriques comporte deux aspects.
- Compter les métriques en tranches. Ci-dessus, nous avons expliqué ce que c'est et pourquoi c'est important pour nous.
- Compter les valeurs moyennes.
L'approche classique du calcul des valeurs moyennes consiste à résumer tous les indicateurs et à les diviser par leur nombre. Cette approche ne fonctionne pas toujours bien car elle prend en compte les cas dégénérés. Par exemple, nous savons que la plupart des bugs que nous corrigeons en une journée. Mais il y a des cas dégénérés - par exemple, un ticket est perdu ou un employé quitte - alors il faut plus de temps pour le réparer. Supposons que nous ayons eu six bogues pour la période considérée. Nous en avons décidé cinq en un jour et un sur 115. Il s'avère que la correction moyenne d'un bug est de 20 jours. Mais ce chiffre ne reflète pas la réalité: nous corrigeons presque toujours les erreurs de la journée, et un ticket long affecte significativement cet indicateur.
Dans de tels cas, le centile vient à la rescousse. Il s'agit de la valeur maximale (dans notre cas, les métriques), qui correspond au pourcentage spécifié d'objets. Par exemple, le 80e centile est une valeur qui ne dépasse pas 80% des objets de l'échantillon. Dans notre cas, une telle valeur serait une valeur de 1, puisque 83% des objets ne la dépassent pas.
Ici, le troisième plan apparaît - le temps pour lequel nous comptons les métriques. Presque toutes nos mesures comptent en 30 jours.
Nous considérons les métriques avec des coupes comme suit:
- d'abord toutes les lignes ensemble,
- puis nous coupons à tour de rôle
- puis nous détaillons: nous faisons une coupure dans les files d'attente avec une coupure pour tous les types de tâches.
Chaque section suivante de la métrique affine la précédente. La valeur moyenne de toutes les files d'attente, types et statuts de tâches donne une idée générale. Nous considérons ensuite la valeur des files d'attente individuelles afin de comprendre comment les choses se passent avec la documentation technique, utilisateur ou interne. Au dernier niveau, le plus détaillé, nous travaillons sur une ligne «queue + type et état».
De plus, nous dirons comment nous considérons les mesures de performance.
Nombre de tâches fermées
Comme nous le considérons: selon le nombre de tâches qui sont fermées dans l'intervalle [il y a 31 jours; hier].
Le nombre de tâches mises en œuvre
Comme nous le considérons: selon le nombre de tâches pour lesquelles le début du travail est dans l'intervalle [il y a 31 jours; hier].
Le nombre de jours avant l'embauche
Comme nous le considérons:
- Pour chaque tâche qui a été mise au travail dans la période spécifiée (date de début dans le Tracker dans l'intervalle [il y a 31 jours; hier]), nous considérons le nombre de jours complets écoulés entre l'instruction (date de création du champ) et le début de la tâche (date de début du champ) .
- Nous résumons toutes les valeurs obtenues lors de la première étape.
- Nous divisons le montant reçu par le nombre de tâches pour lesquelles nous avons effectué le premier élément.
Pour les centiles, l'élément 3 est omis, les valeurs sont triées par ordre croissant et la valeur qui correspond au centile donné est sélectionnée.
Nombre de jours pour terminer
Comme nous le considérons.
- Pour chaque tâche terminée dans la période spécifiée (date de fin dans le Tracker dans l'intervalle [il y a 31 jours; hier]), nous considérons le nombre de jours complets écoulés entre le début du travail (date de début de champ) et la tâche (date de fin de champ).
- Nous résumons toutes les valeurs obtenues lors de la première étape.
- Nous divisons le montant reçu par le nombre de tâches pour lesquelles nous avons effectué le premier élément.
Pour les centiles, l'élément 3 est omis, les valeurs sont triées par ordre croissant et la valeur qui correspond au centile donné est sélectionnée.
Le nombre de tâches sans réaction plus de 14 jours
Comme nous le croyons: par le nombre de tâches dans lesquelles rien ne s'est passé pendant plus de 14 jours. Il est déterminé par le champ mis à jour dans le Tracker: la valeur du champ doit être inférieure à «hier - 14 jours».
Dette technique
Comme nous le considérons: par le nombre de tâches pour lesquelles le statut Backlog est défini dans le Tracker.
Implémentation technique du calcul des métriques de performance
Au niveau supérieur, le système de comptage métrique se compose des composants et des liens d'information suivants.
Programme de comptage métrique planifié
Nous utilisons Nirvana , une plateforme informatique universelle. Il décrit formellement l'ordre dans lequel les processus sont lancés. Avec le planificateur interne (planificateur), Nirvana nous remplace par un ensemble de scripts bash et cron.
Un programme écrit en Python s'exécute régulièrement et demande les données nécessaires au calcul des métriques.
Système de définition des tâches
Les données pour calculer les métriques dans notre cas sont stockées dans Yandex.Tracker. En tant qu'interface avec les données, nous utilisons l'API Python Yandex.Tracker - il s'agit d'un wrapper sur l'API HTTP, qui permet de recevoir plus rapidement et plus facilement des informations dans des structures de données adaptées à un traitement ultérieur.
Vous pouvez choisir un système pratique avec une API appropriée, par exemple, Jira.
Système de préparation des cartes
Après avoir calculé les métriques sur la base des données de Yandex.Tracker, notre programme génère des fichiers JSON et les transfère au service interne Yandex.Statistics pour dessiner des graphiques.
Vous pouvez utiliser une sorte de bibliothèque JS qui peut créer des graphiques. Un aperçu de quelques solutions similaires est sur Habré:
15 meilleures bibliothèques JavaScript
Dans la partie suivante, nous décrirons comment nous considérons les mesures de qualité de la documentation utilisateur.