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 assistenza per i progetti open source per risolvere i problemi relativi alla documentazione dei progetti
- Offrire ai redattori tecnici l'opportunità di acquisire esperienza nell'open source
- Aumentare la consapevolezza su open source, documentazione e scrittura 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
Durante la stagione di Documenti, le organizzazioni possono partecipare inviando una proposta di progetto. La proposta di progetto include:
- Informazioni sull'organizzazione
- Una descrizione del problema riscontrato nel progetto
- 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 del lavoro
- Un budget del progetto
- Eventuali informazioni aggiuntive, ad esempio l'esperienza dell'organizzazione in programmi simili o qualsiasi altra informazione che possa aiutare gli amministratori di Season of Docs a comprendere il progetto e il problema
Una volta accettata l'iscrizione al programma, le organizzazioni reclutano e assumono direttamente i propri autori tecnici. Season of Docs utilizza Open Collective per finanziare le organizzazioni, che pagano i redattori tecnici tramite Open Collective. I budget e i pagamenti dei progetti sono trasparenti: i budget sono inclusi nelle proposte di progetto dell'organizzazione disponibili sul sito di Season of Docs e i pagamenti sono visibili nell'account Open Collective di Season of Docs.
Le organizzazioni vengono considerate aver completato il programma con esito positivo quando inviano il report del caso di studio. Alle organizzazioni viene inoltre chiesto di completare valutazioni mensili durante il programma e tre sondaggi di follow-up trimestrali durante l'anno successivo al completamento del programma.
Momenti salienti del 2022
"Dopo il rilascio del nuovo documento, le visite giornaliere a Casbin e Casdoor sono quasi raddoppiate e i tassi di rimbalzo sono diminuiti di circa il 30%", Casbin
"Un risultato piacevole di questo progetto è stato vedere [i nostri autori 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 a reclutare due autori tecnici di talento, il che è molto difficile in una configurazione standard. Questi autori continuano a essere collaboratori attivi di OpenMined e con loro abbiamo avuto un'esperienza di lavoro fantastica." - OpenMined
"Inoltre, il nuovo manuale è molto più facile per i neofiti della spettrometria di massa computazionale. Per fare un esempio, la sovvenzione CZI fornisce anche borse di studio per persone storicamente svantaggiate e alcuni dei beneficiari hanno utilizzato il nuovo manuale di OpenMS per iniziare il periodo di tirocinio di sei settimane e hanno dato recensioni positive al nuovo manuale." - OpenMS
Dati di riepilogo del 2022
Nel 2022, il programma Season of Docs ha accettato 31 progetti su 67 richieste e 30 progetti lo hanno completato con successo. Delle 31 organizzazioni accettate, 17 erano richiedenti abituali.
Per i 31 progetti accettati sono stati assunti 58 autori tecnici. Più di 190 addetti alla scrittura tecnica hanno manifestato il loro interesse a partecipare al programma aggiungendo i propri dati di contatto e i link ai loro portfolio nel repository GitHub di Season of Docs.
Per il programma del 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 ritiene che il proprio progetto di documentazione sia stato un successo
Informazioni sulle organizzazioni
Le organizzazioni che hanno partecipato alla Stagione dei documenti 2022 rappresentavano una vasta gamma di progetti open source. Il gruppo del 2022 includeva:
- Strumenti di sviluppo, come AsyncAPI e SpyderIDE
- Linguaggi di programmazione e framework, 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 di hardware e robotica, come ExpressLRS e Open-RMF
- Progetti di dati, come GeomScale, GeomStats, OpenMined e Weaviate
- Progetti cloud e di infrastruttura, 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 la licenza open source utilizzata.
Informazioni sui progetti di documentazione
Problemi relativi alla documentazione
I principali problemi che le organizzazioni speravano di risolvere con la documentazione del programma 2022 includevano:
Tieni presente che le organizzazioni potrebbero segnalare più problemi relativi alla documentazione. Per maggiori dettagli, consulta la pagina dei risultati della Stagione della documentazione 2022, che contiene i link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Tipi di documentazione creati
La documentazione di procedura è stata il tipo di documentazione più menzionato nei case study del 2022.
Altri tipi di documentazione menzionati nei casi d'uso includevano:
- Guida rapida
- Glossario
- Domande frequenti
- Knowledgebase
- Componenti
- Contenuti di blog/social media
- Guida per i manutentori
Alcune di queste categorie sono imprecise e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Per maggiori dettagli, consulta la pagina dei risultati della Stagione della documentazione 2022, che contiene i link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Budget
La richiesta di budget media è stata 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
I progetti descritti nei casi studio e le metriche utilizzate per valutare il successo dei progetti di documentazione.
Le metriche principali proposte erano:
Altre metriche proposte incluse:
- Più richieste di pull/contributi alla documentazione
- Feedback più diretto sulle pagine della documentazione
- Tempo trascorso sulla pagina
- Problemi segnalati (come sostituto dell'utilizzo)
- Partecipanti ai forum
- Numero di partner/volontari/integrazioni
- Frequenza di rimbalzo ridotta
- Maggiore consapevolezza nella comunità.
A causa del breve lasso di tempo tra il completamento dei progetti di scrittura tecnica e l'invio dei casi d'uso, la maggior parte del gruppo del 2022 non è stata in grado di raccogliere dati sufficienti al momento dell'invio dei casi d'uso per determinare se le metriche iniziali erano 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 proprie metriche o le hanno riviste.
Per maggiori dettagli, consulta la pagina dei risultati della Stagione della documentazione 2022, che contiene i link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Collaborazione con gli autori tecnici
Nell'ambito del programma Season of Docs, i progetti devono reclutare, sottoporre a colloquio, assumere e pagare direttamente i redattori tecnici. Gli autori tecnici possono aggiungersi alla directory gestita da Season of Docs nel nostro repository GitHub, ma il personale di Season of Docs non controlla né consiglia gli autori tecnici.
Best practice per l'assunzione di autori tecnici per progetti open source
Ai progetti è stato chiesto di condividere le best practice per il reclutamento, l'assunzione e la collaborazione con i redattori tecnici. I consigli principali erano:
Assunzione di personale
- Intervista meno candidati e utilizza una sessione pratica dal vivo anziché limitarti a esaminare i CV
- Dai più valore alle competenze di comunicazione scritta e orale rispetto alla padronanza del linguaggio o degli strumenti del progetto
- Fai domande dirette su come il tecnico della scrittura acquisirà le conoscenze di dominio necessarie per lavorare al tuo progetto
- Chi è entusiasta della missione del progetto e condivide i valori fondamentali dell'open source ha maggiori probabilità di rimanere motivato per l'intero progetto
- Accetta candidature da tutto il mondo, perché una varietà di punti di vista e background contribuirà al tuo progetto, ma tieni presente che avere autori e mentori in troppi fusi orari diversi potrebbe richiedere un grande impegno extra per mantenere una buona comunicazione.
Assunzioni
- Utilizza un contratto che delinei chiaramente gli elementi da consegnare, le scadenze dei pagamenti e impegni di tempo specifici
- Se il tuo progetto presenta molte incognite, includi un traguardo per la scoperta o la ricerca separato dalla creazione della documentazione
Coordinamento e comunicazione
- Tieni un log delle riunioni in cui registri le decisioni per consentire a tutti coloro che lavorano al progetto di comprendere più facilmente il contesto e i passaggi successivi
- Indica chiaramente quali comunicazioni sono previste e con quale frequenza, che si tratti di chiamate settimanali, email giornaliere o aggiornamenti dello stato in un canale di chat
- Rispondi in modo rapido e fornisci un feedback chiaro che includa il "perché" e non solo il "cosa"
- Mettere in contatto i tuoi autori tecnici con la community più ampia per fornire loro il contesto e socializzare il loro lavoro
Processi e strumenti
- Creare una procedura di documentazione che duri oltre il programma della Stagione dei documenti e a cui l'intera community possa contribuire
- La revisione della documentazione richiede almeno lo stesso tempo ed è altrettanto intensa della revisione del codice. Assicurati di dedicare tempo sufficiente a questa operazione
Alcuni consigli sono stati modificati e condensati per maggiore chiarezza.
Come nel programma del 2021, la maggior parte dei redattori tecnici del Season of Docs 2022 ha presentato domanda direttamente alle organizzazioni con cui collaborava.
Problemi comuni nella collaborazione con i redattori tecnici
Nel programma del 2022, un numero inferiore di progetti ha segnalato problemi di collaborazione con i redattori tecnici. Il problema più grande è stato l'impossibilità dei 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 proprio 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 del paese dello scrittore e non è stato possibile importarlo.
Sondaggi di follow-up
Ai partecipanti del 2022 verranno inviati tre sondaggi di follow-up a maggio, agosto e novembre 2023. Aggiorneremo questa sezione con i risultati man mano che vengono ricevuti.
Domande future
Come sempre, più impariamo sulla documentazione in open source, più vogliamo imparare.
Nelle stagioni future, ci auguriamo di:
- Raccogliere più metadati del progetto per cercare correlazioni tra età del progetto, dimensioni della community o esigenze di lingua e documentazione
- Analizza i progetti di documentazione per verificare se possono essere generalizzati in modelli condivisibili
- Sviluppare una rubrica per le interviste ai redattori tecnici nei progetti open source
Anche se ci sono molte domande che vorremmo esaminare, vogliamo anche rispettare il tempo degli amministratori e dei manutentori dei progetti open source che partecipano alla Stagione dei documenti. La massima priorità del programma è aiutare i progetti a risolvere i problemi relativi alla documentazione.