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:
- 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 in 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 2021
Modifiche al programma per il 2021
Nel 2019 e nel 2020, le organizzazioni e i redattori tecnici hanno presentato domanda di partecipazione al programma Season of Docs separatamente e i redattori tecnici sono stati abbinati alle organizzazioni dagli amministratori del programma. Le organizzazioni hanno fornito mentori che collaboravano con i redattori tecnici, che ricevevano uno stipendio per il loro lavoro in base alla località. Il programma ha misurato il grado di soddisfazione dei Technical Writer, dei mentor e degli amministratori dell'organizzazione per la 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 redattori tecnici.
- Organizzazioni che hanno presentato proposte di progetto, inclusi un budget e le metriche proposte
- I Technical Writer non si candidano più tramite Google per essere abbinati alle organizzazioni, ma si candidano direttamente alle organizzazioni accettate
- Le organizzazioni accettate hanno ricevuto sovvenzioni tramite Open Collective, che hanno utilizzato per pagare i redattori tecnici
- Il compenso per gli autori tecnici è stato stabilito dalle organizzazioni
- Le organizzazioni hanno inviato valutazioni finali e case study e hanno risposto ai sondaggi di follow-up
Risultati generali del 2021
Organizzazioni
- Le modifiche al programma del 2021 hanno portato a una riduzione delle richieste di partecipazione (nel 2021 abbiamo registrato il 30% in meno di richieste rispetto al 2020), ma gli amministratori delle organizzazioni 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 è concentrata sulla creazione di documentazione per ridurre il carico dei manutentori (riducendo i problemi/le domande) e/o aumentare la partecipazione al progetto (da parte degli utenti o dei collaboratori del progetto).
- Il 50% delle organizzazioni accettate ha creato tutorial o contenuti di istruzioni.
- Più del 50% delle organizzazioni accettate ha considerato la propria documentazione attuale carente, disorganizzata o obsoleta.
- In genere, i progetti volevano misurare l'efficacia della documentazione tramite le interazioni, in particolare un numero inferiore di problemi segnalati e un maggior numero di visitatori dei documenti e di partecipazione ai progetti.
- A novembre 2022, 25 dei 30 progetti hanno risposto:
- 18 progetti hanno dichiarato di aver raggiunto le metriche originali
- 5 progetti hanno soddisfatto le metriche riviste
- 2 progetti hanno dichiarato che era ancora troppo presto per dirlo
Partecipazione al programma
- Il reclutamento, l'assunzione e il pagamento dei technical writer è stata la parte più difficile del programma per gli amministratori dell'organizzazione.
- A novembre 2022, 24 delle 30 organizzazioni hanno risposto:
- 18 organizzazioni stavano ancora collaborando con i loro autori tecnici della stagione di Documenti (come collaboratori continuativi o come risorsa per rispondere alle domande)
- 4 organizzazioni hanno collaborato con i loro autori tecnici di Season of Docs in un ruolo a pagamento
- 18 organizzazioni stavano ancora collaborando con i loro autori tecnici della stagione di Documenti (come collaboratori continuativi o come risorsa per rispondere alle domande)
Novità principali del 2021
- Diversi progetti hanno indicato che il loro autore tecnico intendeva continuare a lavorare al progetto dopo la fine del programma Season of Docs
- Metanorma ha ricevuto così tante richieste di autori tecnici qualificati che ha trovato fondi corrispondenti per assumere un altro autore che lavorasse insieme all'autore supportato da Season of Docs durante il programma.
- Moja Global ha riscontrato che la community era molto coinvolta nella documentazione e ha creato un nuovo gruppo di lavoro per la documentazione per consentire a un maggior numero di collaboratori di partecipare alla documentazione del progetto.
Dati di riepilogo del 2021
Nel 2021, 82 organizzazioni hanno presentato domanda e 30 organizzazioni open source sono state accettate nel programma. Per i criteri di selezione, consulta la guida alla creazione dell'applicazione. L'elenco completo delle organizzazioni partecipanti è disponibile sul sito web di 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 hanno partecipato alla Stagione dei documenti 2021 rappresentavano una vasta gamma di progetti open source. Il gruppo 2021 includeva:
- Progetti di lingua di grandi dimensioni come Julia, Perl e R
- Progetti in ambito educativo, climatico, fintech, sanitario, servizi bibliotecari, machine learning, spettrometria di massa, contratti pubblici e robotica
- Progetti incentrati sugli sviluppatori, tra cui strumenti di chaos engineering, fuzzer, SDK di chatbot, pipeline di analisi della composizione del 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 sono stati la sottocategoria più grande. Il gruppo 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 dimensione della base utenti).
Abbiamo chiesto ai progetti di indicare la licenza open source utilizzata.
I problemi di documentazione delineati dalle organizzazioni del 2021 sono molto comuni sia nei progetti open source sia nella documentazione tecnica in generale.
I principali problemi che le organizzazioni speravano di risolvere nel programma del 2021 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 2021, che contiene i link ai case study completi di ogni organizzazione.
Tipi di documentazione creati
I tutorial sono stati il tipo di documentazione più menzionato nei case study del 2021.
Altri tipi di documentazione menzionati nei casi d'uso includevano pipeline di Docs as Code, diagrammi, glossari, guide di stile, domande frequenti, internazionalizzazione, codelab, modelli di contenuti, moduli, documentazione dei concetti, messaggi di errore, ricerche utente, file readme, knowledge base.
Alcune di queste categorie sono imprecise e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Diversi progetti hanno fatto riferimento specificamente all'utilizzo del framework Diátaxis come guida per la pianificazione dei tipi di documentazione.
Per maggiori dettagli, consulta la pagina dei risultati della Stagione della documentazione 2021, che contiene i link ai case study completi di ogni organizzazione.
Budget
Nel 2021, la richiesta di budget media è stata di 10.200 $e la mediana di 10.000 $. Solo tre organizzazioni hanno richiesto e ricevuto la sovvenzione massima possibile (15.000 $) e altre tre hanno richiesto la sovvenzione minima possibile (5.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 includevano stelle di GitHub, tempo trascorso sulla pagina, conversioni della mailing list, test qualitativi degli utenti, numero di partecipanti ai 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 casi di studio, la maggior parte del gruppo del 2021 non è riuscita a raccogliere dati sufficienti per determinare se le metriche iniziali erano state raggiunte o meno.
Per maggiori dettagli, consulta la pagina dei risultati della Stagione della documentazione 2021, che contiene i link ai case study completi di ogni organizzazione.
Collaborazione con gli autori tecnici
La più grande modifica al programma della Stagione dei documenti nel 2021 ha riguardato il modo in cui i progetti collaboravano con i redattori tecnici. Nelle stagioni precedenti, i redattori tecnici si candidavano direttamente a Google, venivano abbinati ai progetti dagli amministratori del programma e ricevevano un assegno fisso direttamente da Google.
Nel 2021, i redattori tecnici si sono candidati direttamente ai progetti, che hanno stabilito il budget per il compenso dei redattori tecnici, con i pagamenti effettuati tramite il fondo Open Collective della Stagione dei documenti.
La maggior parte dei progetti che hanno partecipato al programma del 2021 aveva poca o nessuna esperienza nel reclutare o assumere autori di manuali tecnici e molti progetti hanno indicato questa parte della procedura come quella che richiede più assistenza. In risposta a questo feedback, il team di Season of Docs ha aggiunto alla guida del programma la documentazione per la creazione di contratti per gli autori tecnici.
Consigli per l'assunzione
Ai progetti è stato chiesto di fare raccomandazioni ad altri progetti interessati a partecipare alla Stagione dei documenti. I principali consigli per le assunzioni sono stati:
- Condividi i materiali di reclutamento per i redattori tecnici il prima possibile, anche prima di ricevere l'accettazione al programma. Chiedi alla tua community di segnalare possibili candidati.
- Condividere contenuti al di fuori dei canali del progetto. Utilizza un linguaggio inclusivo e incoraggia direttamente i candidati provenienti da contesti sottorappresentati a presentare domanda.
- Scopri quali strumenti sono essenziali per la procedura di creazione della documentazione e recluta autori tecnici con esperienza nell'utilizzo di questi strumenti.
- Fornisci al redattore tecnico aspettative chiare su attività da svolgere e traguardi, canali di comunicazione e controlli, nonché tempistiche e procedure di pagamento.
- Valuta la possibilità di investire nei membri della community e di aiutarli a crescere come autori tecnici utilizzando il programma di tutoraggio per autori tecnici di Season of Docs.
- Prevedi più tempo del previsto per l'onboarding dei redattori tecnici, per rispondere alle domande e fornire assistenza durante il programma, soprattutto se il redattore tecnico non ha esperienza nel dominio del tuo progetto.
- Documenta la procedura di reclutamento, assunzione e onboarding da utilizzare per i progetti futuri.
(Nota: non tutti i progetti indicati nei case study hanno reclutato candidati per il ruolo di Technical Writer).
Problemi comuni nella collaborazione con i redattori tecnici
I redattori tecnici di diversi progetti hanno dovuto abbandonare il progetto a causa del COVID o di altre malattie o per responsabilità familiari legate alla pandemia. Alcuni progetti hanno segnalato problemi di comunicazione relativi a mancate corrispondenze dei fusi orari o problemi di connettività a internet.
I progetti hanno riscontrato di aver sottovalutato le difficoltà legate all'onboarding nelle loro community o alla configurazione della suite di strumenti per la documentazione del progetto.
Per alcuni progetti si sono verificati ritardi nel pagamento dei redattori tecnici a causa di problemi bancari con Open Collective o perché i paesi di origine dei redattori avevano limitazioni di pagamento.
La documentazione del programma relativa alle commissioni di Open Collective non era chiara: Google copriva le commissioni di transazione di Open Collective per il trasferimento iniziale dei fondi ai progetti, ma non le commissioni di transazione imposte da altri canali di pagamento (ad esempio le commissioni di conversione valutaria). Cercheremo di chiarire questo aspetto nella documentazione dei programmi futuri.
Sondaggi di follow-up
Nell'ambito del programma Season of Docs, ai progetti è stato chiesto di partecipare a sondaggi di follow-up. Tre sondaggi sono stati inviati a maggio, agosto e novembre 2022.
Il sondaggio di follow-up ha chiesto ai progetti di confermare che i link alla proposta e ai casi studio erano ancora attivi. Il sondaggio includeva anche domande sul successo dei progetti (come stabilito dalle metriche impostate nel case study) e sulla partecipazione e sulla retribuzione continua dei Technical Writer del progetto:
- Stai ancora collaborando con il tuo autore tecnico di Season of Docs?
- Se il tuo autore tecnico sta ancora lavorando al progetto, riceve un compenso?
- A questo punto, ritieni che il tuo progetto di documentazione sia riuscito?
Domande future
Come sempre, più impariamo sulla documentazione in open source, più vogliamo imparare. Nelle stagioni future, ci auguriamo di scoprire:
- Indica se i domini dei progetti sono correlati alla scelta del tipo di documento o della metrica
- Quali pratiche di assunzione e onboarding dei redattori tecnici sono più efficaci per il completamento del progetto e il loro mantenimento
- 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 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.