Choisir les bonnes métriques pour votre projet

L'objectif de ce guide est d'aider les organisations à comprendre quels types de problèmes pourraient être résolus grâce à une meilleure documentation, et comment choisir les métriques appropriées pour les projets de documentation.

Phase actuelle:
Résultats annoncés. Consultez le calendrier.

Énoncez votre problème.

Avant de vous lancer dans le choix d'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 demandes d'extraction de nos documents d'intégration prend trop de temps. Les contributeurs abandonnent et quittent le site."
  • "Nous avons constaté qu'il y avait trop de problèmes à résoudre pour comprendre les codes d'erreur."
  • "Notre pipeline CI/CD est irrégulier. Trop de tests échouent pour des raisons mal comprises."
  • « Les gens ont l'air grincheux à 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 indiqué ? Gardez à l'esprit que les problèmes peuvent avoir des causes multiples ou se recouper.

  • "La fusion des demandes d'extraction pour la documentation d'intégration prend beaucoup de temps, car nous n'avons pas d'instructions claires sur le style. Soit les examinateurs remettent à examiner les relations publiques parce qu'ils ne savent pas quoi faire, soit ils passent de l'un à l'autre avec des contributeurs au sujet de la mise en forme."
  • "Les utilisateurs doivent signaler des problèmes, car ils ne trouvent pas d'informations sur les codes d'erreur dans la documentation."
  • "Nos tests CI/CD échouent, car notre fournisseur rencontre des limites et des délais avant expiration du forfait."
  • "Les gens 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 avec une documentation nouvelle ou améliorée ?

  • "Si nous avions un guide de style, les contributeurs pouvaient le consulter avant d'envoyer leurs demandes d'extraction. Les évaluateurs sauront quoi vérifier. Les contributeurs et les contributeurs n'auraient pas à débattre de la mise en forme, du ton et du style."
  • "Si nous disposions d'une documentation sur les codes d'erreur, les utilisateurs pouvaient y trouver leurs réponses au lieu de créer des problèmes."
  • "Une documentation plus complète ne semble pas pouvoir résoudre notre problème de CI/CD."
  • "Nous pourrions commencer chaque réunion par une blague à cogne ! En créant une collection de blagues de tonnes, nous pourrions commencer nos réunions avec le sourire."

Soyez précis

Pouvez-vous quantifier le problème ?

  • "Que signifie 'la fusion des relations publiques prend trop de temps' ? Deux mois ? Deux semaines ? Combien de temps les contributeurs devront-ils attendre d'être examiné avant de renoncer ?"
  • "Combien de problèmes liés aux codes d'erreur sont 'trop de problèmes' ?"
  • "Hmmm ... c'est grincheux 'trop grincheux' ?"

Vérifier la mesurabilité

Comment vérifieriez-vous la métrique que vous proposez ? Peut-il être mesuré facilement et avec précision ? La mesure dépend-elle de la personne qui effectue la mesure ?

  • "Nous pouvons facilement mesurer le temps écoulé depuis l'ouverture d'une demande d'extraction et depuis combien de temps un examen a été demandé. Nous ne pouvons pas vraiment mesurer exactement quand un contributeur abandonne. »
  • "Nous pouvons compter le nombre de problèmes marqués 'code d'erreur' ou rechercher le texte du code d'erreur dans les problèmes."
  • « Nous ne pouvons pas vraiment mesurer la grinchitude des gens de manière tactile ou précise. »

Ajouter une métrique secondaire

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

  • "L'examen des demandes d'extraction plus longues prend plus de temps. Il faut définir des seuils différents selon la taille des PR. Nous voulons mesurer le temps nécessaire à la fusion pour les PR de petite, moyenne, grande et gigantesque."
  • "Nous avons pu vérifier le nombre de visites reçues par notre documentation sur le code d'erreur et voir s'il correspond au nombre moins important de problèmes ouverts."

Sélectionnez une période

  • "Nous pensons qu'il est raisonnable de prendre deux semaines pour fusionner les relations publiques de petite à moyenne envergure. En outre, toutes les demandes d'extraction devraient être fusionnées en un mois. Nous allons donc mesurer toutes les deux semaines. »
  • "Il n'est pas logique de mettre à jour quotidiennement le nombre de problèmes liés au code d'erreur, car le délai habituel pour résoudre un problème est d'une semaine. Nous la mesurerons chaque semaine."

Définition d'objectifs

Quel changement auriez-vous besoin de voir dans l'indicateur que vous avez sélectionné pour dire 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 atteignions notre objectif de fermer toutes les nouvelles relations publiques en moins d'un mois, ce serait une réussite. Si notre délai moyen pour boucler les grandes demandes d'extraction diminuait de deux semaines, nous obtiendrions d'excellents résultats."
  • "Dans l'idéal, nous n'aurions pas de nouveaux problèmes liés aux erreurs. Mais nous considérerions que notre projet est réussi si nous voyions une baisse de 50% des problèmes liés aux erreurs. »