Season of Docs è un programma di sostenibilità gestito dall'Ufficio per i programmi open source di Google. Gli obiettivi di Season of Docs sono:
- Fornire supporto ai progetti open source per risolvere i problemi dei progetti con la documentazione
- Offrire ai redattori tecnici l'opportunità di acquisire esperienza nell'open source
- Sensibilizzare sull'open source, sulla documentazione e sulla redazione tecnica
- Raccogliere e condividere informazioni sulle metriche efficaci nella documentazione open source
Ulteriori informazioni su Season of Docs sono disponibili sul sito web del programma.
Panoramica del programma 2022
Come funziona Season of Docs
In Season of Docs, le organizzazioni presentano la domanda inviando una proposta di progetto. La proposta di progetto include:
- Informazioni sull'organizzazione
- Una descrizione del problema che il progetto sta affrontando
- In che modo il progetto utilizzerà la documentazione per risolvere il problema
- In che modo il progetto misurerà l'efficacia della documentazione (metriche)
- Una sequenza temporale per il lavoro
- Un budget di progetto
- Eventuali informazioni aggiuntive, ad esempio l'esperienza dell'organizzazione in programmi simili o qualsiasi altra informazione che aiuti gli amministratori di Season of Docs a comprendere il progetto e il problema
Una volta accettate nel programma, le organizzazioni assumono direttamente i propri redattori tecnici. Season of Docs utilizza Open Collective per finanziare le organizzazioni, che a loro volta pagano i redattori tecnici tramite Open Collective. I budget e i pagamenti dei progetti sono trasparenti: i budget sono inclusi nelle proposte di progetto delle organizzazioni disponibili sul sito di Season of Docs e i pagamenti sono visibili nell'account Open Collective di Season of Docs.
Le organizzazioni sono considerate aver completato il programma con successo quando inviano il report dello studio di caso. Alle organizzazioni viene inoltre chiesto di completare le valutazioni mensili durante il programma e tre sondaggi di follow-up trimestrali durante l'anno successivo al completamento del programma.
Punti salienti del 2022
"Dopo la pubblicazione del nuovo documento, le visite giornaliere a Casbin e Casdoor sono quasi raddoppiate e le frequenze di rimbalzo sono diminuite di circa il 30%". - Casbin
"Un risultato entusiasmante di questo progetto è stato vedere i nostri redattori tecnici assumere ruoli di leadership nella nostra community. Entrambi i collaboratori ora guidano i gruppi di lavoro e le riunioni della community, oltre a contribuire alla progettazione e alla manutenzione dei nostri progetti". - moja-global
"[GSoD] ci ha aiutato ad assumere due redattori tecnici di talento, cosa molto difficile in una configurazione normale, che continuano a essere collaboratori open source attivi di OpenMined e con cui abbiamo avuto un'ottima esperienza lavorativa". - OpenMined
"Inoltre, il nuovo manuale è molto più facile da usare per i principianti della spettrometria di massa computazionale. Per illustrare questo punto: la sovvenzione CZI fornisce anche stipendi a persone storicamente svantaggiate e alcuni beneficiari hanno utilizzato il nuovo manuale OpenMS per dare il via al periodo di stage di sei settimane e hanno fornito recensioni positive del nuovo manuale". - OpenMS
Dati di sintesi del 2022
Nel 2022, il programma Season of Docs ha accettato 31 progetti su 67 richieste e 30 progetti hanno completato il programma con successo. Delle 31 organizzazioni accettate, 17 erano richiedenti abituali.
I 31 progetti accettati hanno assunto 58 redattori tecnici. Più di 190 redattori tecnici hanno indicato il loro interesse a partecipare al programma aggiungendo i loro dati di contatto e i link ai loro portfolio nel repository GitHub di Season of Docs.
Per il programma 2022:
- Il 100% delle organizzazioni ha avuto un'esperienza positiva con la procedura di richiesta
- Il 100% delle organizzazioni ha avuto un'esperienza positiva con la documentazione/i contenuti del sito web del programma
- Il 93% delle organizzazioni ha avuto un'esperienza positiva con il programma
- Il 90% delle organizzazioni ha ritenuto che il proprio progetto di documentazione abbia avuto successo
Informazioni sulle organizzazioni
Le organizzazioni che hanno partecipato a Season of Docs 2022 rappresentavano una vasta gamma di progetti open source. La coorte del 2022 includeva:
- Strumenti di sviluppo, come AsyncAPI e SpyderIDE
- Linguaggi e framework di programmazione, come Julia, LFortran, R, e p5.js
- Progetti scientifici, come CERN-HSF e SymPy
- Applicazioni per utenti finali, come Mautic, Open Food Facts, Talawa e Ushahidi
- Progetti hardware e di robotica, come ExpressLRS e Open-RMF
- Progetti di dati, come GeomScale, GeomStats, OpenMined, e Weaviate
- Progetti cloud e infrastrutturali, come cert-manager, NimbleEdge, e Cilium
Non abbiamo raccolto metadati sui progetti (ad esempio data di fondazione, distribuzione geografica dei collaboratori, numero di collaboratori o dimensioni della base utenti).
Abbiamo chiesto ai progetti di indicare quale licenza open source utilizzavano.
Informazioni sui progetti di documentazione
Problemi di documentazione
I principali problemi che le organizzazioni speravano di risolvere con la documentazione nel programma 2022 includevano:
Tieni presente che le organizzazioni potevano segnalare più problemi di documentazione. Per maggiori dettagli, consulta la pagina dei risultati di Season of Docs 2022 results page, che include i link alle proposte di progetto originali e agli studi di caso completi per ogni organizzazione.
Tipi di documentazione creati
La documentazione di tipo "Istruzioni" è stata il tipo di documentazione più comunemente menzionato negli studi di caso del 2022.
Altri tipi di documentazione menzionati negli studi di caso includono:
- Guida rapida
- Glossario
- Domande frequenti
- KnowledgeBase
- Componenti
- Contenuti di blog/social media
- Guida per i manutentori
Alcune di queste categorie sono vaghe e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Per maggiori dettagli, consulta la pagina dei risultati di Season of Docs 2022 results page, che include i link alle proposte di progetto originali e agli studi di caso completi per ogni organizzazione.
Budget
La richiesta di budget media era di 11.679 $e la mediana di 12.150 $. Cinque organizzazioni hanno richiesto e ricevuto la sovvenzione più alta disponibile (15.000 $) e tre hanno richiesto la più bassa (tra 5.000 e 7.000 $).
Le metriche
Nei loro studi di caso, i progetti hanno descritto le metriche che utilizzavano per valutare il successo dei loro progetti di documentazione.
Le principali metriche proposte erano:
Altre metriche proposte includono:
- Più richieste di pull/contributi di documentazione
- Più feedback diretti sulle pagine di documentazione
- Tempo trascorso sulla pagina
- Problemi sollevati (come proxy per l'utilizzo)
- Partecipanti ai forum
- Numero di partner/volontari/integrazioni
- Frequenza di rimbalzo ridotta
- Maggiore consapevolezza nella community.
A causa della breve finestra di tempo tra il completamento dei progetti di redazione tecnica e l'invio degli studi di caso, la maggior parte della coorte del 2022 non è stata in grado di raccogliere dati sufficienti al momento dell'invio degli studi di caso per determinare se le metriche iniziali fossero state raggiunte o meno.
Man mano che riceveremo le risposte ai sondaggi di follow-up nel 2023, aggiorneremo questo report per aggiungere informazioni sui progetti che hanno raggiunto le loro metriche o le hanno riviste.
Per maggiori dettagli, consulta la pagina dei risultati di Season of Docs 2022 results page, che include i link alle proposte di progetto originali e agli studi di caso completi per ogni organizzazione.
Collaborazione con i redattori tecnici
Nel programma Season of Docs, i progetti devono reclutare, intervistare, assumere e pagare direttamente i redattori tecnici. I redattori tecnici possono aggiungersi alla directory gestita da Season of Docs nel nostro repository GitHub, ma il personale di Season of Docs non verifica né consiglia i redattori tecnici.
Best practice per l'assunzione di redattori tecnici per progetti open source
Ai progetti è stato chiesto di condividere le loro best practice per il reclutamento, l'assunzione e la collaborazione con i redattori tecnici. Le principali raccomandazioni sono state:
Reclutamento
- Intervista a meno candidati e utilizza una sessione di pratica dal vivo, anziché limitarti a esaminare i CV
- Valuta le capacità di comunicazione scritta e orale rispetto alla competenza nella lingua o negli strumenti del tuo progetto
- Poni domande dirette su come il redattore tecnico acquisirà le conoscenze del dominio necessarie per lavorare al tuo progetto
- È più probabile che una persona entusiasta della missione del tuo progetto e che condivida i valori open source fondamentali rimanga motivata per l'intero progetto
- Sii aperto ai candidati di tutto il mondo, perché una diversità di punti di vista e background aiuterà il tuo progetto, ma tieni presente che avere redattori e mentori in troppi fusi orari in conflitto potrebbe richiedere molto impegno extra per mantenere una buona comunicazione
Assunzione
- Utilizza un contratto che specifichi chiaramente i risultati finali, i programmi di pagamento e gli impegni di tempo specifici
- Se il tuo progetto presenta molte incognite, includi una milestone per la scoperta o la ricerca separata dalla creazione della documentazione
Coordinamento e comunicazione
- Tieni un registro delle riunioni in cui registri le decisioni per consentire a tutti coloro che lavorano al progetto di comprendere il contesto e i passaggi successivi
- Specifica chiaramente la comunicazione prevista e la sua frequenza, che si tratti di chiamate settimanali, email giornaliere o aggiornamenti di stato in un canale di chat
- Rispondi e fornisci feedback chiari che includano il "perché" e non solo "il cosa"
- Metti in contatto i tuoi redattori tecnici con la community più ampia per fornire loro il contesto e socializzare il loro lavoro
Processi e strumenti
- Crea un processo di documentazione che duri oltre il programma Season of Docs e a cui possa contribuire l'intera community
- La revisione della documentazione richiederà almeno lo stesso tempo ed è altrettanto intensa della revisione del codice; assicurati di concedere tempo sufficiente
Alcune raccomandazioni sono state modificate e condensate per maggiore chiarezza.
Come nel programma 2021, la maggior parte dei redattori tecnici di Season of Docs 2022 ha presentato la domanda direttamente alle organizzazioni con cui ha lavorato.
Problemi comuni nella collaborazione con i redattori tecnici
Nel programma 2022, meno progetti hanno segnalato problemi nella collaborazione con i redattori tecnici. Il problema principale è stato l'impossibilità per i redattori tecnici di completare il programma a causa di malattia, assunzione di un lavoro a tempo pieno o impossibilità di rispettare l'impegno di tempo.
Un progetto ha segnalato che il progetto di documentazione dipendeva dal lavoro svolto nell'ambito di Google Summer of Code e che queste dipendenze erano difficili da gestire. Un altro progetto ha riscontrato difficoltà quando l'hardware che il redattore tecnico doveva documentare è stato confiscato dal Ministero della Difesa nel paese del redattore e non poteva essere importato.
Sondaggi di follow-up
Nel maggio, agosto e novembre 2023 verranno inviati tre sondaggi di follow-up ai partecipanti del 2022. Aggiorneremo questa sezione con i risultati man mano che li riceveremo.
Domande future
Come sempre, più impariamo sulla documentazione open source, più vogliamo imparare!
Nelle stagioni future, speriamo di:
- Raccogliere più metadati del progetto per cercare correlazioni tra età del progetto, dimensioni della community o lingua e esigenze di documentazione
- Analizzare i progetti di documentazione per verificare se possono essere generalizzati in modelli condivisibili
- Sviluppare una griglia per intervistare i redattori tecnici nei progetti open source
Sebbene ci siano molte domande che vorremmo approfondire, vogliamo anche rispettare il tempo degli amministratori e dei manutentori dei progetti open source che partecipano a Season of Docs. La priorità assoluta del programma è aiutare i progetti a risolvere i problemi con la documentazione.