Scegli le metriche giuste per il tuo progetto

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

Fase attuale:
Il programma Stagione di Documenti 2021 si è concluso il 14 dicembre 2021. Consulta la cronologia.

Indica il problema

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

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

Sviluppa un'ipotesi

Cerca la causa e l'effetto. A cosa potrebbe essere dovuto il problema che hai dichiarato? 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 perché riscontriamo limitazioni e timeout del piano da parte del nostro provider."
  • "Le persone sono scortesi durante le nostre riunioni settimanali perché iniziano alle 5:30 del mattino nel loro fuso orario."

Proponi una soluzione

È 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 richieste di pull. I revisori sapranno cosa controllare. I revisori 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ì, anziché aprire problemi."
  • "Hmm, non sembra che una documentazione migliore possa risolvere il nostro problema CI/CD."
  • "Potremmo iniziare ogni riunione con una barzelletta toc-knock! 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 PR richiede troppo tempo"? Due mesi? Due settimane? Per quanto tempo i collaboratori rimarranno in attesa della revisione 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 cattiveria 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 è sempre la stessa?

  • "Le RP più lunghe richiedono più tempo per la revisione; dovremmo avere soglie diverse per RP di dimensioni diverse. Vogliamo misurare il tempo di unione per PR 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. Pertanto, la misurazione verrà eseguita 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 notare 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 riuscissimo a raggiungere il nostro obiettivo di chiudere ogni nuovo PR in meno di un mese, sarebbe un successo. Se il nostro tempo medio per chiudere grandi PR diminuisse di due settimane, sarebbe un enorme successo".
  • "L'ideale sarebbe che non riscontreremmo nuovi problemi relativi agli errori. Tuttavia, considereremo il nostro progetto un successo se riscontreremo un calo del 50% dei problemi relativi agli errori aperti.