Scegli le metriche giuste per il tuo progetto

Questa guida ha lo scopo di aiutare le organizzazioni a comprendere quali tipi di problemi possono essere risolti con una documentazione migliore e come scegliere le metriche appropriate per i progetti di documentazione.

Fase attuale:
Sviluppo della documentazione. Consulta la cronologia.

Indica il problema

Prima di passare alla scelta di una metrica, assicurati di aver compreso bene il problema che stai cercando di risolvere. Fornisci informazioni quanto più specifiche possibile.

  • "L'unione delle richieste di pull per la nostra documentazione di onboarding richiede troppo tempo. I collaboratori si arrendono e spariscono".
  • "Abbiamo rilevato troppi problemi aperti per aiutarci a comprendere i codici di errore."
  • "La nostra pipeline CI/CD è instabile. Troppi test non hanno esito positivo per motivi poco compresi."
  • "Le persone sembrano disorientate alle nostre riunioni settimanali."

Elaborare un'ipotesi

Cerca causa ed effetto. A cosa potrebbe essere dovuto il problema che hai segnalato? Tieni presente che i problemi possono avere cause diverse o sovrapposte.

  • "Ci vuole così tanto tempo per unire le richieste di pull alla documentazione di onboarding, perché non disponiamo di indicazioni chiare sullo stile. I revisori scoraggiano dal rivedere il PR perché non sanno cosa fare o consultano i collaboratori in merito alla formattazione."
  • "Gli utenti devono aprire i problemi perché non possono trovare informazioni sui codici di errore nella documentazione."
  • "I nostri test CI/CD hanno esito negativo a causa di limitazioni e timeout del piano da parte del nostro provider."
  • "Le persone partecipano alle nostre riunioni settimanali perché sono alle 05:30 del loro fuso orario."

Proponi una soluzione

Si tratta di un problema che potrebbe essere risolto con una documentazione nuova o migliore?

  • "Se avessimo a disposizione una guida di stile, i responsabili delle commissioni potevano verificarla prima di inviare le loro PR. I recensori sapranno cosa controllare. Recensori e collaboratori non dovrebbero discutere di formattazione, tono e stile".
  • "Se disponessimo della documentazione sui codici di errore, gli utenti potrebbero trovare le risposte lì, anziché aprire i problemi."
  • "Mmm, sembra che una documentazione migliore non possa risolvere il nostro problema CI/CD."
  • "Potremmo iniziare ogni incontro con una barzelletta per fare colpo! Creare una raccolta di battute importanti ci aiuterebbe a iniziare i nostri incontri con un sorriso."

Diventa specifico

Riesci a quantificare il problema?

  • "Cosa significa in realtà "ci vuole troppo tempo per unire i PR"? Due mesi? Due settimane? Quanto tempo dovranno aspettare i collaboratori per la revisione prima di rinunciare?"
  • "Quanti problemi relativi al codice di errore sono 'troppi problemi'?"
  • "Mmm... quanto è burbero 'troppo scontroso'?"

Verificare la misurabilità

Come verificheresti la metrica proposta? Si può misurare facilmente e in modo accurato? La misurazione dipende da chi esegue la misurazione?

  • "Possiamo misurare facilmente per quanto tempo una richiesta di pull è stata aperta e da quanto tempo è stata richiesta una revisione. Non possiamo misurare esattamente quando un collaboratore si arrende".
  • "Possiamo contare quanti problemi sono contrassegnati con l'etichetta "error-code" o cercare all'interno dei problemi per il testo del codice di errore."
  • "Non possiamo misurare la malinconia delle persone in modo tattico o preciso."

Aggiungi una metrica secondaria

Esistono altre metriche che potrebbero aiutarti a comprendere se la tua documentazione sta risolvendo il tuo problema? La metrica target è la stessa in tutti i casi?

  • "Le PR più lunghe richiedono più tempo per essere esaminate; dovremmo avere soglie diverse per dimensioni diverse di PR. Vogliamo misurare il tempo di unione per le PR piccole, medie, grandi e gigantesche."
  • "Potremmo controllare quante visite ha ricevuto la nostra documentazione sui codici di errore e vedere se quel numero è correlato a un minor numero di problemi aperti."

Scegli un periodo di tempo

  • "Riteniamo che due settimane siano un tempo ragionevole per unire le PR di piccole e medie dimensioni; tutte le PR dovrebbero essere unite entro un mese. Quindi le misureremo ogni due settimane".
  • "Non ha senso aggiornare ogni giorno il numero di problemi relativi al codice di errore, perché in genere il tempo a nostra disposizione per chiudere un problema è di una settimana. Lo misureremo ogni settimana."

Fissa obiettivi

Quante modifiche devi apportare alla metrica selezionata per dichiarare che il progetto è stato un successo? Valuta la possibilità di definire obiettivi quantitativi per le metriche che hai scelto.

  • "Se riuscissimo a chiudere ogni nuovo PR in meno di un mese, sarebbe un successo. Se il nostro tempo medio per chiudere grandi PR diminuisca di due settimane, sarebbe un successo strepitoso."
  • "Idealmente, non dovremmo vedere nuovi problemi relativi agli errori. Tuttavia, considereremmo riusciti il nostro progetto se rilevassimo un calo del 50% dei problemi correlati a errori."