L'objectif de ce guide est d'aider les organisations à comprendre quels types de problèmes pourraient être résolus avec une meilleure documentation et comment choisir les critères appropriés pour les projets de documentation.
Phase actuelle:
Le programme Season of Docs 2021 s'est terminé le 14 décembre 2021. 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 disparaissent."
- "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."
Élaborer une hypothèse
Recherchez la cause et l'effet. 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 pull request, car ils ne savent pas quoi faire, ou ils échangent avec les 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 au niveau du plan."
- "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 problèmes."
- "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 à 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 relations publiques prend trop de temps' ?' Deux mois ? Deux semaines ? Combien de temps les contributeurs seront-ils prêts à attendre avant d'abandonner ?"
- "Combien de problèmes liés au code d'erreur sont 'trop nombreux' ?"
- "Hmmm… "trop grincheux", c'est à quel point ?"
Vérifier la mesurabilité
Comment vérifieriez-vous la métrique que vous proposez ? Peut-il être mesuré facilement et précisément ? Les mesures dépendent-elles de la personne qui effectue la mesure ?
- "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 problèmes ouverts."
Sélectionnez une période
- "Nous pensons que deux semaines sont un délai raisonnable pour fusionner les demandes d'annonces de petite à moyenne taille. De plus, tous les demandes d'annonces devraient être fusionnées en 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
Quel changement auriez-vous besoin de voir dans la mesure sélectionnée 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 atteignons notre objectif de clôturer chaque nouvelle demande de partenariat en moins d'un mois, ce sera un succès. Si le délai 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. Nous considérerons notre projet comme un succès si nous observons une diminution de 50% du nombre de demandes liées à des erreurs."
Informations connexes
- Consultez le guide de l'administrateur de l'organisation pour obtenir de l'aide concernant vos tâches liées aux rapports.