Fase attuale:
Il programma per la stagione di Documenti 2021 è terminato il 14 dicembre 2021. Consulta la cronologia.
Informazioni su Season of Docs
Season of Docs è un programma di sostenibilità gestito dall'ufficio per i programmi open source di Google. Gli obiettivi di Season of Docs sono i seguenti:
- Fornire assistenza per progetti open source per risolvere i problemi dei progetti con la documentazione
- Offri ai tecnici l'opportunità di acquisire esperienza nell'open source
- Sensibilizzare l'opinione pubblica su open source, documentazione e scrittura tecnica
- Raccogliere e condividere informazioni sulle metriche efficaci nella documentazione open source
Ulteriori informazioni sulla stagione dei documenti sono disponibili sul sito web del programma.
Panoramica del programma 2021
Modifiche al programma del 2021
Nel 2019 e nel 2020, le organizzazioni e i Technical Writer hanno presentato domanda separatamente per il programma Season of Docs, e i Technical writer sono stati assegnati alle organizzazioni in base agli amministratori del programma Season of Docs. Le organizzazioni hanno offerto dei mentori per lavorare con i Technical Writer, che hanno ricevuto uno stipendio per il loro lavoro in base alla località in cui si trovano. Il programma ha misurato se i Technical Writer, i Mentori e gli Amministratori dell'organizzazione erano soddisfatti della loro partecipazione al programma, ma non ha misurato i risultati della documentazione.
Nel 2021, il team di Season of Docs ha apportato modifiche significative al programma, spostando l'attenzione sulla misurazione dei risultati della documentazione e consentendo una maggiore flessibilità alle organizzazioni e ai Technical Writer.
- Organizzazioni applicate con proposte di progetto, inclusi un budget e le metriche proposte
- I Technical Writer non fanno più domanda tramite Google per trovare corrispondenze con le organizzazioni, ma fanno domanda direttamente per le organizzazioni accettate
- Le organizzazioni accettate hanno ricevuto donazioni tramite Open Collective, che hanno utilizzato per pagare i Technical Writer
- Il compenso per i Technical Writer è stato fissato dalle organizzazioni
- Le organizzazioni hanno inviato valutazioni finali e case study e hanno risposto a sondaggi di follow-up
Risultati generali 2021
Organizzazioni
- I cambiamenti nel programma del 2021 hanno portato a un numero inferiore di organizzazioni che hanno presentato domanda (abbiamo visto il 30% in meno di organizzazioni che hanno presentato domanda nel 2021 rispetto al 2020), ma gli amministratori dell'organizzazione del 2021 erano leggermente più soddisfatti del programma rispetto agli amministratori del 2020 (93% contro 91%)
Problemi, tipi di documenti e metriche
- La maggior parte dei progetti si concentrava sulla creazione di documentazione per ridurre il carico di lavoro del manutentore (riducendo problemi/domande) e/o aumentare la partecipazione al progetto (da parte degli utenti o dei collaboratori del progetto).
- Il 50% delle organizzazioni accettate ha creato contenuti tutorial o tutorial.
- Oltre il 50% delle organizzazioni accettate ha considerato la propria documentazione attuale mancante, disorganizzata o obsoleta.
- I progetti in genere volevano misurare l'efficacia della loro documentazione attraverso le interazioni, in particolare meno problemi sollevati e più visitatori dei documenti e partecipazione ai progetti.
- A novembre 2022, hanno risposto 25 progetti su 30:
- 18 progetti hanno dichiarato di aver soddisfatto le metriche originali
- 5 progetti hanno soddisfatto le metriche riviste
- 2 progetti hanno affermato che era ancora troppo presto per dirlo
Partecipazione al programma
- Reclutare, assumere e pagare i Technical Writer è stata la parte più difficile del programma per gli amministratori dell'organizzazione.
- A novembre 2022, 24 organizzazioni su 30 hanno risposto:
- 18 organizzazioni stavano ancora lavorando con i loro Technical Writer della Stagione di Documenti (come collaboratore continuo o come risorsa per rispondere alle domande)
- 4 organizzazioni stavano lavorando con i Technical Writer della Stagione di Documenti con un ruolo a pagamento
- 18 organizzazioni stavano ancora lavorando con i loro Technical Writer della Stagione di Documenti (come collaboratore continuo o come risorsa per rispondere alle domande)
In evidenza nel 2021
- Diversi progetti hanno indicato che il proprio Technical Writer intendeva continuare a lavorare al progetto dopo la fine del programma Season of Docs (Stagione dei documenti).
- Metanorma ha fatto candidare così tanti Technical Writer qualificati da trovare fondi adeguati per assumere un altro scrittore che lavorasse insieme alla Stagione degli scrittori supportati da Documenti durante il programma.
- Moja Global ha scoperto che la community era molto coinvolta nella documentazione e ha istituito un nuovo gruppo di lavoro sulla documentazione per consentire a un maggior numero di collaboratori di partecipare alla documentazione del progetto
Dati di riepilogo 2021
Nel 2021, 82 organizzazioni hanno presentato domanda e 30 organizzazioni open source sono state accettate al programma. Per i criteri di selezione, consulta la guida alla creazione della domanda di partecipazione. L'elenco completo delle organizzazioni partecipanti è disponibile sul sito web Season of Docs. Tutte le 30 organizzazioni accettate hanno inviato il report finale del case study per completare la partecipazione al programma del 2021.
Informazioni sulle organizzazioni
Le organizzazioni che partecipano alla stagione dei documenti 2021 hanno rappresentato una vasta gamma di progetti open source. La coorte del 2021 includeva:
- Progetti linguistici di grandi dimensioni come Julia, Perl e R
- Progetti nei settori dell'istruzione, del clima, della tecnofinanza, della sanità, dei servizi bibliotecari, del machine learning, della spettrometria di massa, dei contratti pubblici e della robotica
- Progetti incentrati sugli sviluppatori, tra cui strumenti di ingegneria del caos, fuzzer, SDK per chatbot, pipeline di analisi della composizione software, strumenti di monitoraggio delle prestazioni e strumenti di programmazione visiva
- Progetti di documentazione per strumenti di documentazione, come Redocly e Metanorma
I progetti dell'ecosistema Python erano la sottocategoria più ampia. La coorte del 2021 includeva ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite e SymPy.
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.
I problemi di documentazione individuati dalle organizzazioni del 2021 sono molto comuni sia nei progetti open source che nella documentazione tecnica in generale.
I principali problemi che le organizzazioni speravano di risolvere nel programma del 2021 includono:
Tieni presente che le organizzazioni potrebbero segnalare più problemi relativi alla documentazione. Per ulteriori informazioni, consulta la pagina dei risultati relativa alla stagione dei documenti 2021, che contiene un link a case study completi per ogni organizzazione.
Tipi di documentazione creata
I tutorial sono stati il tipo di documentazione più comunemente menzionato nei case study del 2021.
Altri tipi di documentazione menzionati nei case study includevano pipeline di Docs-as-code, diagramma, Glossario, Guida di stile, domande frequenti, internazionalizzazione, codelab, modello di contenuti, moduli, documentazione dei concetti, messaggi di errore, ricerca sugli utenti, file Readme, knowledge base.
Alcune di queste categorie non sono chiare e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Diversi progetti hanno fatto riferimento in modo specifico all'utilizzo del framework Diátaxis come guida per la pianificazione dei loro tipi di documentazione.
Per ulteriori informazioni, consulta la pagina dei risultati relativa alla stagione dei documenti 2021, che contiene un link a case study completi per ogni organizzazione.
Budget
Nel 2021, la richiesta di budget medio è stata di 10.200 $e la media di 10.000 $. Solo tre organizzazioni hanno richiesto e ricevuto la sovvenzione massima possibile (15.000 $), mentre altre tre hanno richiesto la sovvenzione più bassa possibile (5.000 $).
Metriche
I progetti hanno delineato nei loro case study le metriche che utilizzavano per valutare il successo dei loro progetti di documentazione.
Le principali metriche proposte erano:
Altre metriche proposte includevano stelle di GitHub, tempo trascorso sulla pagina, conversioni della mailing list, test qualitativi degli utenti, numero di partecipanti nei forum, numero di partner/volontari/integrazioni.
A causa del breve lasso di tempo tra il completamento dei progetti di scrittura tecnica e l'invio dei case study, la maggior parte della coorte del 2021 non è stata in grado di raccogliere dati sufficienti per determinare se le metriche iniziali erano state soddisfatte.
Per ulteriori informazioni, consulta la pagina dei risultati relativa alla stagione dei documenti 2021, che contiene un link a case study completi per ogni organizzazione.
Collaborazione con i Technical Writer
Il cambiamento più importante al programma Stagione dei documenti nel 2021 ha riguardato il modo in cui i progetti hanno collaborato con i Technical Writer. Nelle stagioni precedenti, i Technical Writer facevano domanda direttamente a Google, ricevendo dei progetti da parte degli amministratori del programma e ricevevano uno stipendio fisso direttamente da Google.
Nel 2021, i Technical Writer hanno presentato domanda direttamente per i progetti e i progetti hanno fissato il budget per il compenso del Technical Writer, con pagamenti effettuati tramite la Season of Docs, Open Collective Fund.
La maggior parte dei progetti partecipanti al programma del 2021 aveva poca o nessuna esperienza nel reclutare o nell'assumere scrittori tecnici e molti progetti definivano questa parte del processo come una che necessita di maggiore supporto. In risposta a questo feedback, il team per la stagione dei documenti ha aggiunto alla guida al programma la documentazione per la creazione di contratti di Technical Writer.
Consigli sulle assunzioni
Ai progetti è stato chiesto di fornire suggerimenti per altri progetti interessati a partecipare alla stagione di Documenti. Le principali raccomandazioni sulle assunzioni sono state:
- Condividi il materiale per la selezione del personale per i Technical Writer il prima possibile, anche prima che il tuo nome venga accettato nel programma. Chiedi alla community di segnalare possibili candidati.
- Condividere su larga scala al di fuori dei canali del progetto. Utilizza un linguaggio inclusivo e incoraggia direttamente i candidati provenienti da background sottorappresentati a presentare domanda.
- Scopri quali strumenti sono essenziali per il processo di creazione della documentazione e recluta tecnici con esperienza nell'utilizzo di questi strumenti.
- Crea aspettative chiare per il Technical writer in merito a risultati finali e traguardi, canali e controlli di comunicazione, procedure e tempistiche di pagamento.
- Prendi in considerazione l'idea di investire nei membri della community e di aiutarli a crescere come Technical writer utilizzando il Technical writer di Season of Docs per fornire tutoraggio e coaching.
- Dedica più tempo del previsto all'onboarding dei Technical Writer, alle risposte alle domande e alla fornitura di assistenza durante il programma, soprattutto se questi non hanno esperienza nel dominio del tuo progetto.
- Documenta la procedura di assunzione, assunzione e inserimento da utilizzare per i progetti futuri.
Nota: non tutti i progetti indicati nei case study in cui sono stati reclutati candidati per Technical Writer.
Problemi comuni nella collaborazione con i Technical Writer
I Technical Writer in diversi progetti hanno dovuto abbandonare il lavoro a causa del COVID o di altre malattie oppure a causa di responsabilità familiari legate alla pandemia. Alcuni progetti hanno segnalato problemi di comunicazione relativi a errate corrispondenze di fuso orario o problemi di connettività a internet.
I progetti hanno scoperto di aver sottovalutato le difficoltà legate all'onboarding nelle comunità o alla configurazione della Toolchain dei documenti del progetto.
Alcuni progetti hanno avuto ritardi nei pagamenti ai loro Technical Writer a causa di problemi bancari con Open Collective o perché i paesi di origine degli autori avevano limitazioni ai pagamenti.
La documentazione del programma relativa alle commissioni di Open Collective non era chiara: Google copriva le commissioni delle transazioni Open Collective per il trasferimento iniziale di fondi ai progetti, ma non le commissioni di transazione imposte da alcuni altri canali di pagamento (come le commissioni di conversione di valuta). Faremo del nostro meglio per renderlo più chiaro nella documentazione per i programmi futuri.
Sondaggi di follow-up
Nell'ambito del programma Season of Docs, è stato chiesto ai progetti di partecipare a sondaggi di follow-up. A maggio, agosto e novembre 2022 sono stati inviati tre sondaggi.
Il sondaggio di follow-up ha chiesto ai progetti di confermare che la proposta e i link ai case study erano ancora attivi. Il sondaggio includeva anche domande sul successo dei loro progetti (come determinato dalle metriche impostate nel case study) e sulla partecipazione continua e sulla retribuzione dei Technical Writer del progetto:
- Stai ancora lavorando con il tuo Technical Writer della stagione di Documenti?
- Se il tuo Technical Writer sta ancora lavorando al tuo progetto, riceve un compenso in qualche modo?
- A questo punto, ritieni che il tuo progetto di documentazione abbia successo?
Domande future
Come sempre, più impariamo a conoscere la documentazione in open source, più vogliamo imparare. Nelle prossime stagioni, ci auguriamo di apprendere:
- Se i domini del progetto sono correlati alla scelta del tipo di documento o della metrica
- Quali pratiche di assunzione e onboarding del Technical writer sono più efficaci per il completamento del progetto e la fidelizzazione del Technical Writer
- Tempistiche ragionevoli per misurare l'efficacia della documentazione
Anche se ci sono molte domande che vorremmo esaminare, vogliamo anche rispettare il tempo degli amministratori e dei gestori dei progetti open source che partecipano alla stagione di Documenti. La priorità assoluta del programma è supportare i progetti nella risoluzione dei loro problemi con la documentazione.