Choisir les bonnes métriques pour votre projet

Ce guide vise à aider les organisations à comprendre les types de problèmes qui peuvent être résolus grâce à une meilleure documentation et à choisir les métriques appropriées pour les projets de documentation.

Phase actuelle:
Études de cas publiées. Voir la chronologie.

Décrivez votre problème

Avant de choisir une métrique, assurez-vous de bien comprendre le problème que vous essayez de résoudre. Soyez aussi précis(e) que possible.

  • "La fusion des requêtes pull pour notre documentation d'intégration prend trop de temps. Les contributeurs abandonnent et s'en vont."
  • "Nous constatons que trop de demandes d'aide pour comprendre les codes d'erreur sont ouvertes."
  • "Notre pipeline CI/CD est instable. Trop de tests échouent pour des raisons mal comprises."
  • "Les participants semblent grincheux lors de nos réunions hebdomadaires."

Développer une hypothèse

Recherchez les causes et les effets. Quelle pourrait être la cause du problème que vous avez décrit ? Gardez à l'esprit que les problèmes peuvent avoir plusieurs causes ou des causes qui se chevauchent.

  • "Il faut tellement de temps pour fusionner les requêtes pull pour la documentation d'intégration, car nous n'avons pas de consignes claires sur le style. Les examinateurs repoussent l'examen de la demande de publication parce qu'ils ne savent pas quoi faire, ou ils échangent avec les contributeurs au sujet de la mise en forme."
  • "Les utilisateurs doivent ouvrir des problèmes, car ils ne trouvent pas d'informations sur les codes d'erreur dans la documentation."
  • "Nos tests CI/CD échouent, car nous rencontrons des limites de plan et des délais avant expiration de notre fournisseur."
  • "Les participants sont grincheux lors de nos réunions hebdomadaires, car elles ont lieu à 5h30 du matin dans leur fuseau horaire."

Proposer une solution

Ce problème pourrait-il être résolu par de la documentation nouvelle ou améliorée ?

  • "Si nous avions un guide de style, les contributeurs pourraient le consulter avant d'envoyer leurs PR. Les examinateurs sauront ce qu'ils doivent vérifier. Les réviseurs et les contributeurs n'auraient pas à se disputer sur la mise en forme, le ton et le style."
  • "Si nous avions une documentation sur les codes d'erreur, les utilisateurs pourraient y trouver les réponses à leurs questions au lieu d'ouvrir des demandes."
  • "Hmm, il ne semble pas qu'une meilleure documentation résolve notre problème de CI/CD."
  • "Nous pourrions commencer chaque réunion avec une blague "toc-toc". Créer une collection de blagues de Knock-Knock nous aiderait à commencer nos réunions avec le sourire."

Soyez précis

Pouvez-vous quantifier le problème ?

  • "Que signifie vraiment "la fusion des demandes de publication prend trop de temps" ? Deux mois ? Deux semaines ? Combien de temps les contributeurs attendront-ils avant d'abandonner ?"
  • "Combien de problèmes liés à un code d'erreur correspondent à "trop de problèmes" ?"
  • "Hmmm… À quel point est-il grincheux ?"

Vérifier la mesurabilité

Comment vérifier la métrique proposée ? Peut-il être mesuré facilement et précisément ? La mesure dépend-elle de la personne qui la réalise ?

  • "Nous pouvons facilement mesurer la durée d'une demande d'extraction et la durée écoulée depuis la demande d'examen. Nous ne pouvons pas vraiment mesurer avec précision quand un contributeur abandonne."
  • "Nous pouvons compter le nombre de problèmes tagués "code d'erreur" ou rechercher le texte du code d'erreur dans les problèmes."
  • "Nous ne pouvons pas vraiment mesurer la mauvaise humeur des utilisateurs de manière délicate ou précise."

Ajouter une métrique secondaire

Y a-t-il d'autres métriques qui vous aideraient à comprendre si votre documentation résout votre problème ? Votre métrique cible est-elle la même dans tous les cas ?

  • "Les PR plus longues prennent plus de temps à examiner. Nous devrions avoir des seuils différents pour les différentes tailles de PR. Nous souhaitons mesurer le temps de fusion pour les PR de petite, moyenne, grande et gigantesque envergure."
  • "Nous pourrions vérifier le nombre de visites que reçoit notre documentation sur les codes d'erreur et voir si ce nombre est corrélé à une diminution du nombre de demandes ouvertes."

Sélectionnez une période

  • "Nous pensons que deux semaines est un délai raisonnable pour fusionner les PR de petite à moyenne envergure. Toutes les PR doivent être fusionnées dans un délai d'un mois. Nous allons donc mesurer tous les deux semaines."
  • "Il n'a pas de sens de mettre à jour le nombre de problèmes liés à un code d'erreur chaque jour, car le délai moyen de résolution d'un problème est d'une semaine. Nous allons le mesurer chaque semaine."

Définissez des objectifs

Quelle variation devez-vous constater dans la métrique sélectionnée pour affirmer que le projet a été un succès ? Envisagez de définir des objectifs quantitatifs pour les métriques que vous avez choisies.

  • "Si nous atteignons notre objectif de clôturer chaque nouvelle demande de publication en moins d'un mois, ce sera un succès. Si notre temps moyen de clôture des demandes d'accès importantes diminuait de deux semaines, ce serait un grand succès."
  • "Dans l'idéal, nous ne devrions plus voir de nouveaux problèmes liés à des erreurs. Toutefois, nous considérerons notre projet comme un succès si nous observons une diminution de 50% du nombre de demandes liées à des erreurs."