Fase attuale:
Sviluppo della documentazione. Consulta la cronologia.
Season of Docs è un programma di sostenibilità gestito dall'ufficio per i programmi open source di Google. Gli obiettivi di Season of Docs sono:
- Fornisci supporto per progetti open source in modo da risolvere i problemi relativi ai progetti con la documentazione
- Offri ai tecnici l'opportunità di acquisire esperienza nell'open source
- Aumenta la consapevolezza in merito all'open source, alla documentazione e alla 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
In Season of Docs, le organizzazioni possono presentare domanda inviando una proposta di progetto. La proposta del progetto include:
- Informazioni sull'organizzazione
- Una descrizione del problema affrontato dal progetto
- In che modo il progetto utilizzerà la documentazione per risolvere il problema
- In che modo il progetto misurerà l'efficacia della documentazione (metriche)
- La tempistica del lavoro
- Il budget di un progetto
- Qualsiasi informazione aggiuntiva, come l'esperienza dell'organizzazione in programmi simili, o qualsiasi altra informazione che possa aiutare gli amministratori di Season of Docs a comprendere il loro progetto e i loro problemi
Una volta accettate al programma, le organizzazioni reclutano e assumono direttamente i propri Technical Writer. Season of Docs utilizza Open Collective per finanziare le organizzazioni, mentre le organizzazioni pagano i Technical Writer tramite Open Collective. I budget e i pagamenti dei progetti sono trasparenti; i budget sono inclusi nelle proposte di progetti dell'organizzazione disponibili sul sito della stagione dei documenti, mentre i pagamenti sono visibili nell'account Open Collective per la stagione dei documenti.
Si considera che le organizzazioni abbiano completato con successo il programma quando inviano il report sul case study. Alle organizzazioni viene inoltre chiesto di completare valutazioni mensili durante il programma e tre sondaggi trimestrali di follow-up durante l'anno successivo al completamento del programma.
In evidenza nel 2022
"Dopo il rilascio 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 fantastico di questo progetto è stato vedere che [i nostri Technical writer] diventare ruoli di leadership nella nostra community. Entrambi i collaboratori sono ora a capo delle riunioni dei gruppi di lavoro e della comunità, oltre a contribuire alla progettazione e alla manutenzione dei nostri progetti." —moja-global
"[GSoD] ci ha aiutato a reclutare due Technical Writer di talento, il che è molto difficile in un normale allestimento, che continuano a contribuire attivamente al sistema operativo per OpenMined e con i quali abbiamo avuto un'ottima esperienza lavorativa." – OpenMined
"Inoltre, il nuovo manuale è molto più facile per i neofiti della spettrometria di massa computazionale. Per illustrare questo punto: la sovvenzione CZI offre anche borse di studio a individui storicamente svantaggiati e alcuni premiati hanno utilizzato il nuovo manuale di OpenMS per iniziare il loro periodo di tirocinio di sei settimane e hanno dato recensioni positive del nuovo manuale." - OpenMS
Dati di riepilogo per il 2022
Nel 2022, il programma Season of Docs ha accettato 31 progetti su 67 domande e 30 progetti hanno completato il programma con successo. Delle 31 organizzazioni accettate, 17 erano candidati ricorrenti.
I 31 progetti accettati hanno assunto 58 Technical writer. Più di 190 Technical writer hanno dichiarato il proprio interesse a partecipare al programma aggiungendo i propri dati di contatto e link ai propri 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 partecipano alla stagione di Documenti 2022 hanno rappresentato una vasta gamma di progetti open source. La coorte del 2022 includeva:
- Strumenti di sviluppo, come AsyncAPI e SpyderIDE
- Linguaggio di programmazione e framework come Julia, LFortran, R e p5.js
- Progetti scientifici, come CERN-HSF e SymPy
- Applicazioni dell'utente finale, ad esempio Mautic, Open Food Facts, Talawa e Ushahidi
- Progetti hardware e di robotica, ad esempio ExpressLRS e Open-RMF.
- Progetti di dati, come GeomScale, GeomStats, OpenMined e Weaviate
- Progetti di infrastruttura e cloud, 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 del programma per il 2022 includevano:
Tieni presente che le aziende potrebbero segnalare diversi problemi relativi alla documentazione. Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2022, che contiene link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Tipi di documentazione creata
La documentazione illustrativa è stata il tipo di documentazione più menzionato nei case study del 2022.
Altri tipi di documentazione menzionati nei case study includevano:
- Guida rapida
- Glossario
- Domande frequenti
- Knowledgebase
- Componenti
- Contenuti di blog/social media
- Guida per il mantenitore
Alcune di queste categorie sono incomplete e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2022, che contiene link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Budget
La richiesta di budget medio era di 11.679 $e la media di 12.150 $. Cinque organizzazioni hanno richiesto e ricevuto la sovvenzione più alta disponibile (15.000 $) e tre hanno chiesto il più basso (tra i 5.000 $e i 7.000 $).
Metriche
I progetti hanno delineato nei loro case study le metriche utilizzate per valutare il successo dei progetti di documentazione.
Le principali metriche proposte sono state:
Altre metriche proposte includevano:
- Ulteriori richieste/contributi/richieste di pull della documentazione
- Feedback più diretto sulle pagine della documentazione
- Tempo trascorso sulla pagina
- Problemi sollevati (come proxy per l'utilizzo)
- Partecipanti ai forum
- Numero di partner/volontari/integrazioni
- Frequenza di rimbalzo ridotta
- Aumento della consapevolezza nella community.
A causa del breve lasso di tempo tra la conclusione dei progetti di scrittura tecnica e l'invio dei case study, la maggior parte della coorte del 2022 non è stata in grado di raccogliere dati sufficienti al momento dell'invio dei case study per determinare se le metriche iniziali erano state soddisfatte o meno.
Man mano che riceveremo risposte ai sondaggi di follow-up nel 2023, aggiorneremo questo report per aggiungere informazioni sui progetti che hanno raggiunto le metriche o ne hanno riesaminate le metriche.
Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2022, che contiene link alle proposte di progetto originali e ai case study completi per ogni organizzazione.
Collaborazione con i Technical Writer
Nel programma Season of Docs, i progetti devono reclutare, interviste, assumere e pagare direttamente i Technical writer. I Technical writer possono aggiungersi alla directory gestita da Season of Docs nel nostro repository GitHub, ma lo staff di Season of Docs non verifica né consiglia i Technical writer.
Best practice per assumere Technical Writer per progetti open source
Ai progetti è stato chiesto di condividere le loro best practice per la selezione del personale, l'assunzione e la collaborazione con i Technical Writer. Ecco i consigli principali:
Assunzione di personale
- Intervista un numero minore di candidati e utilizza una sessione di esercitazione dal vivo, anziché limitarti a esaminare i CV.
- Dai valore alle competenze di comunicazione scritta e orale piuttosto che alla competenza nella lingua o negli strumenti del tuo progetto
- Fai domande dirette su come il Technical Writer acquisirà le conoscenze di dominio necessarie per lavorare con il tuo progetto
- Una persona con entusiasmo per la missione del tuo progetto e che condivide i valori fondamentali dell'open source ha maggiori probabilità di mantenere alta la motivazione per l'intero progetto
- Sii disponibile ai candidati provenienti da tutto il mondo, perché la diversità di punti di vista e background sarà utile per il tuo progetto; tuttavia, tieni presente che avere scrittori e mentori in troppi fusi orari in conflitto può richiedere molto impegno in più per mantenere una buona comunicazione.
Assunzione
- Utilizza un contratto che indichi chiaramente i risultati finali, il calendario dei pagamenti e gli impegni temporali specifici
- Se il progetto ha molte incognite, includi un traguardo per l'individuazione o la ricerca separato dalla creazione della documentazione
Coordinamento e comunicazione
- Conserva le decisioni relative alla registrazione del log delle riunioni per permettere a tutti coloro che lavorano al progetto di comprendere il contesto e i passaggi successivi più facilmente
- Descrivi chiaramente ciò che devi comunicare e la frequenza, che si tratti di chiamate settimanali, email giornaliere o aggiornamenti di stato in un canale di chat.
- Rispondi in modo reattivo e fornisci un feedback chiaro che includa il "perché" e non solo "cosa"
- Metti in contatto i tuoi Technical Writer con la comunità più ampia per fornire loro un 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 l'intera community possa contribuire
- La revisione della documentazione richiederà almeno lo stesso tempo e la stessa intensità della revisione del codice; assicurati di lasciare tempo sufficiente
Alcuni consigli sono stati modificati e abbreviati per maggiore chiarezza.
Come nel programma del 2021, la maggior parte dei Technical Writer nella Stagione dei Documenti 2022 si è rivolta direttamente alle organizzazioni con cui lavorava.
Problemi comuni nella collaborazione con i Technical Writer
Nel programma 2022, un numero minore di progetti ha segnalato problemi relativi alla collaborazione con i Technical Writer. Il problema maggiore era l'impossibilità da parte dei Technical writer di completare il programma a causa di malattia, dell'assunzione di un lavoro a tempo pieno o dell'incapacità di rispettare l'impegno in termini di tempo.
Secondo un progetto, 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 avuto difficoltà quando l'hardware che il suo autore tecnico aveva bisogno di documentare è stato confiscato dal Ministero della Difesa nel paese dell'autore e non è stato importato.
Sondaggi di follow-up
A maggio, agosto e novembre 2023 verranno inviati ai partecipanti tre sondaggi di follow-up. Aggiorneremo questa sezione con i risultati man mano che li riceveremo.
Domande future
Come sempre, più impariamo a conoscere la documentazione in open source, più vogliamo saperne di più.
Nelle prossime stagioni, ci auguriamo di:
- Raccogliere più metadati del progetto per cercare correlazioni tra età del progetto, dimensioni della community o esigenze linguistice e di documentazione
- Analizza i progetti di documentazione per vedere se possono essere generalizzati in modelli condivisibili
- Sviluppare una griglia per intervistare i Technical Writer nei progetti open source
Anche se ci sono molte domande che vorremmo approfondire, vogliamo anche rispettare il tempo degli amministratori e dei gestori dei progetti open source che partecipano a Season of Docs. La principale priorità del programma è supportare i progetti nella risoluzione dei loro problemi con la documentazione.