Scegli le metriche giuste per il tuo progetto

Lo scopo di questa guida è aiutare le organizzazioni a capire quali tipi di problemi possono essere risolti con una documentazione migliore e come scegliere le metriche appropriate per i progetti di documentazione.

Fase attuale:
Case study pubblicati. Consulta la cronologia.

Indica il problema

Prima di scegliere una metrica, assicurati di avere compreso bene il problema che stai cercando di risolvere. Fornisci informazioni quanto più specifiche possibile.

  • "L'unione delle richieste pull per la nostra documentazione di onboarding richiede troppo tempo. I collaboratori si arrendono e se ne vanno".
  • "Abbiamo notato che sono stati aperti troppi problemi per ricevere assistenza per la comprensione dei codici di errore."
  • "La nostra pipeline CI/CD è instabile. Troppi test non riescono per motivi poco chiari".
  • "Le persone sembrano scortesi nelle nostre riunioni settimanali."

Sviluppare un'ipotesi

Cerca la causa e l'effetto. Quale potrebbe essere la causa del problema che hai indicato? Tieni presente che i problemi possono avere cause multiple o sovrapposte.

  • "L'unione delle richieste pull per la documentazione di onboarding richiede molto tempo perché non abbiamo indicazioni chiare sullo stile. I revisori rimandano la revisione della RP perché non sanno cosa fare o vanno avanti e indietro con i collaboratori in merito alla formattazione".
  • "Gli utenti devono aprire dei problemi perché non riescono a trovare informazioni sui codici errore nella documentazione."
  • "I nostri test CI/CD non riescono a causa di limitazioni del piano e timeout del nostro fornitore."
  • "Le persone sono scortesi durante le nostre riunioni settimanali perché iniziano alle 5:30 del mattino nel loro fuso orario."

Proporre una soluzione

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

  • "Se avessimo una guida di stile, i committer potrebbero controllarla prima di inviare le loro RP. I revisori saprebbero cosa controllare. I recensori e i collaboratori non dovrebbero discutere di formattazione, tono e stile".
  • "Se avessimo una documentazione relativa ai codici di errore, gli utenti potrebbero trovare le risposte lì, invece di aprire i problemi."
  • "Hmm, non mi sembra che una documentazione migliore possa risolvere il nostro problema di CI/CD."
  • "Potremmo iniziare ogni riunione con una barzelletta. Creare una raccolta di barzellette farebbe iniziare le nostre riunioni con un sorriso."

Fornisci informazioni specifiche

Puoi quantificare il problema?

  • "Cosa significa esattamente "L'unione delle RP richiede troppo tempo"? Due mesi? Due settimane? Quanto tempo i collaboratori dovranno attendere prima di rinunciare?"
  • "Quanti problemi relativi ai codici di errore sono "troppi problemi"?"
  • "Hmmm … quanto è scontroso "troppo scontroso"?"

Verificare la misurabilità

Come controlleresti la metrica proposta? Può essere misurato facilmente e con precisione? La misurazione dipende da chi la esegue?

  • "Possiamo misurare facilmente da quanto tempo è aperta una richiesta di pull e da quanto tempo è stata richiesta una revisione. Non possiamo misurare esattamente quando un collaboratore si arrende".
  • "Possiamo contare il numero di problemi con il tag "error-code" o cercare il testo del codice di errore all'interno dei problemi."
  • "Non possiamo misurare la scontrosità delle persone in modo delicato o accurato."

Aggiungere una metrica secondaria

Esistono altre metriche che ti aiuterebbero a capire se la documentazione sta risolvendo il problema? La metrica target è la stessa in ogni caso?

  • "Le PR più lunghe richiedono più tempo per la revisione. Dovremmo avere soglie diverse per dimensioni diverse delle PR. Vogliamo misurare il tempo di unione per RP piccole, medie, grandi e giganti".
  • "Potremmo controllare quante visite riceve la nostra documentazione relativa ai codici di errore e vedere se questo numero è correlato a un numero inferiore di problemi aperti."

Scegli un periodo di tempo

  • "Riteniamo che due settimane siano un periodo di tempo ragionevole per unire RP di piccole e medie dimensioni. Tutte le RP dovrebbero essere unite entro un mese. Quindi la misurazione verrà effettuata ogni due settimane."
  • "Non ha senso aggiornare quotidianamente il numero di problemi correlati ai codici di errore, perché il tempo medio per la chiusura di un problema è di una settimana. Lo misureremo settimanalmente."

Fissa obiettivi

Quale variazione dovresti riscontrare nella metrica selezionata per affermare che il progetto è stato un successo? Valuta la possibilità di impostare obiettivi quantitativi per le metriche che hai scelto.

  • "Se dovessimo raggiungere il nostro obiettivo di chiudere ogni nuovo RP in meno di un mese, sarebbe un successo. Se il tempo medio per chiudere le RP di grandi dimensioni diminuisse di due settimane, sarebbe un grande successo".
  • "Idealmente, non dovremmo riscontrare nuovi problemi relativi agli errori. Tuttavia, considereremo il nostro progetto un successo se riscontreremo una diminuzione del 50% dei problemi correlati agli errori aperti."