Scegli le metriche giuste per il tuo progetto

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

Fase attuale:
Risultati annunciati tempistiche.

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 se ne vanno".
  • "Abbiamo rilevato troppi problemi aperti per aiutarci a comprendere i codici di errore."
  • "La nostra pipeline CI/CD è instabile. Troppi test non riusciti per motivi poco compresi."
  • "Le persone sembrano irritate alle nostre riunioni settimanali."

Elaborare un'ipotesi

Cerca causa ed effetto. Quale potrebbe essere la causa del problema che hai segnalato? Tieni presente che i problemi possono avere cause multiple o sovrapposte.

  • "Ci vuole così tanto tempo per unire le richieste pull per la documentazione di onboarding, perché non disponiamo di indicazioni chiare sullo stile. I revisori rimandano il PR perché non sanno cosa fare oppure si confrontano con i collaboratori riguardo alla formattazione."
  • "Gli utenti devono aprire i problemi perché non riescono a 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 sono irritate 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 una guida di stile, i responsabili delle commissioni potevano verificarla prima di inviare i PR. I recensori sapranno cosa controllare. Recensori e collaboratori non dovrebbero discutere della formattazione, del tono e dello stile."
  • "Se avessimo a disposizione la documentazione relativa ai codici di errore, gli utenti potevano trovare lì le risposte, anziché aprire problemi."
  • "Mmm, non sembra che una documentazione migliore possa risolvere il nostro problema di CI/CD."
  • "Potremmo iniziare ogni incontro con una battuta! Creare una raccolta di battute importanti ci aiuterebbe a iniziare i nostri incontri con un sorriso."

Sii specifico

Riesci a quantificare il problema?

  • "Cosa significa davvero 'ci vuole troppo tempo per unire i PR"? Due mesi? Due settimane? Quanto tempo devono attendere i collaboratori per la revisione prima di rinunciare?"
  • "Quanti problemi relativi al codice di errore sono "troppi problemi"?"
  • "Mmmh... quanto è scontroso 'troppo scontroso'?"

Controlla la misurabilità

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

  • "Possiamo misurare facilmente da quanto tempo una richiesta di pull è stata aperta e da quanto tempo è stata richiesta una revisione. Non possiamo misurare con precisione quando un collaboratore si arrende".
  • "Possiamo contare quanti problemi sono contrassegnati con 'codice di errore' o cercare all'interno dei problemi per trovare il testo del codice di errore."
  • "Non possiamo davvero misurare la sgradevolezza delle persone in modo tatto o preciso."

Aggiungere una metrica secondaria

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

  • "I PR più lunghi richiedono più tempo per essere esaminati; dovremmo avere soglie diverse per PR di dimensioni diverse. Vogliamo misurare il tempo di unione per PR piccole, medie, grandi ed enormi."
  • "Abbiamo potuto controllare quante visite ha ricevuto la documentazione relativa al codice di errore e vedere se quel numero è correlato a un numero inferiore di problemi aperti".

Scegli un periodo di tempo

  • "Riteniamo che due settimane sia un tempo ragionevole da dedicare all'unione di PR di piccole e medie dimensioni e tutte dovrebbero essere unite entro un mese. Misuriamo ogni due settimane."
  • "Non ha senso aggiornare ogni giorno il numero di problemi relativi al codice di errore, perché in genere il tempo necessario per risolvere un problema è di una settimana. Lo misureremo ogni settimana."

Fissa obiettivi

Quante modifiche dovresti vedere nella metrica selezionata per dichiarare che il progetto è stato un successo? Valuta la possibilità di impostare obiettivi quantitativi per le metriche che hai scelto.

  • "Se riuscissimo a chiudere tutte le nuove PR in meno di un mese, sarebbe un successo. Se il nostro tempo medio per chiudere grandi PR dovesse diminuire di due settimane, ci sarebbe un enorme successo".
  • "Idealmente, non vedremmo nuovi problemi relativi a errori. Tuttavia, considereremmo il nostro progetto un successo se vedessimo un calo del 50% delle problematiche dovute a errori."