Fase attuale:
Il programma Stagione di Documenti 2021 si è concluso 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:
- 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 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; inoltre, gli amministratori del programma Season of Docs hanno assegnato ai Technical writer le organizzazioni. Le organizzazioni hanno fornito mentori per lavorare con i Technical Writer, che hanno ricevuto uno stipendio per il loro lavoro in base alla loro località. Il programma ha misurato l'apprezzamento da parte di Technical writer, tutor e amministratori dell'organizzazione rispetto alla 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, concentrando l'attenzione sulla misurazione dei risultati della documentazione e consentendo una maggiore flessibilità alle organizzazioni e ai Technical writer.
- Organizzazioni applicate alle proposte di progetto, inclusi un budget e le metriche proposte
- I Technical writer non hanno più presentato domanda tramite Google per essere abbinati alle organizzazioni, ma hanno presentato domanda direttamente per le organizzazioni accettate
- Le organizzazioni accettate hanno ricevuto donazioni tramite Open Collective, che hanno utilizzato per pagare i Technical Writer
- La retribuzione per i Technical Writer era fissata dalle organizzazioni
- Le organizzazioni hanno inviato valutazioni finali e case study e hanno risposto a sondaggi di follow-up
Risultati generali del 2021
Organizzazioni
- I cambiamenti nel programma del 2021 hanno portato a un numero inferiore di organizzazioni che hanno presentato domanda (nel 2021 abbiamo registrato il 30% in meno di organizzazioni che hanno presentato domanda nel 2021 rispetto al 2020), ma gli amministratori dell'organizzazione del 2021 sono stati leggermente più soddisfatti del programma rispetto agli amministratori del 2020 (93% rispetto al 91%).
Problemi, doctype e metriche
- La maggior parte dei progetti si è concentrata sulla creazione di documentazione per ridurre il carico del personale di manutenzione (riducendo problemi/domande) e/o aumentare la partecipazione ai progetti (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 loro attuale documentazione mancante, disorganizzata o obsoleta.
- In genere i progetti volevano misurare l'efficacia della propria documentazione attraverso le interazioni, in particolare meno problemi sollevati, più visitatori dei documenti e partecipazione ai progetti.
- A partire da novembre 2022, con 25 progetti su 30 hanno risposto:
- 18 progetti hanno dichiarato di aver soddisfatto le metriche originali
- 5 progetti hanno soddisfatto le metriche riviste
- Due progetti hanno affermato che era ancora troppo presto per dirlo
Partecipazione al programma
- Assumere, 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 Technical Writer della propria stagione di Documenti (sia come collaboratori continui che come risorsa per rispondere alle domande)
- 4 organizzazioni stavano lavorando con il proprio Technical writer Season of Docs con un ruolo retribuito
- 18 organizzazioni stavano ancora lavorando con i Technical Writer della propria stagione di Documenti (sia come collaboratori continui che 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.
- Metanorma ha richiesto tantissimi Technical writer qualificati da trovare i fondi necessari per assumere un altro scrittore che collaborasse con la Season of Docs e durante il programma.
- Moja Global ha scoperto che la comunità si è molto interessata alla documentazione e ha istituito un nuovo gruppo di lavoro della documentazione per consentire a un numero maggiore di collaboratori di partecipare alla documentazione del progetto.
Dati di riepilogo per il 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 di una candidatura. L'elenco completo delle organizzazioni partecipanti è disponibile sul sito web della stagione dei documenti. Tutte le 30 organizzazioni accettate hanno inviato il report finale sul case study per completare la loro partecipazione al programma 2021.
Informazioni sulle organizzazioni
Le organizzazioni che partecipano alla stagione di 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 delineati dalle organizzazioni del 2021 sono molto comuni sia nei progetti open source sia nella documentazione tecnica in generale.
Tra i principali problemi che le organizzazioni speravano di risolvere nel programma del 2021 ci sono:
Tieni presente che le aziende potrebbero segnalare diversi problemi relativi alla documentazione. Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2021, che contiene link a case study completi per ogni organizzazione.
Tipi di documentazione creata
I tutorial sono stati il tipo di documentazione più menzionato nei case study del 2021.
Altri tipi di documentazione menzionati nei case study includevano pipeline di Docs-as-code, Diagram, Glossario, Guida di stile, Domande frequenti, Internazionalizzazione, Codelab, Modello di contenuti, Moduli, Documentazione concettuale, Messaggi di errore, Ricerca sugli utenti, Readme, Knowledgebase.
Alcune di queste categorie sono incomplete e un singolo progetto di documentazione potrebbe contenere più tipi o funzionalità di documentazione.
Diversi progetti a cui viene fatto riferimento in modo specifico utilizzando il framework Diátaxis come guida per la pianificazione dei relativi tipi di documentazione.
Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2021, che contiene link a case study completi per ogni organizzazione.
Budget
Nel 2021, la richiesta di budget medio era di 10.200 $e la media di 10.000 $. Solo tre organizzazioni hanno richiesto e ricevuto la sovvenzione massima possibile (15.000 $) e altre tre hanno richiesto la sovvenzione più bassa possibile (5.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 stelle di GitHub, tempo trascorso sulla pagina, conversioni di mailing list, test qualitativi sugli utenti, numero di partecipanti ai forum, numero di partner/volontari/integrazioni.
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 2021 non è stata in grado di raccogliere dati sufficienti per determinare se le metriche iniziali erano state soddisfatte o meno.
Per ulteriori dettagli, consulta la pagina dei risultati della stagione dei documenti 2021, che contiene link a case study completi per ogni organizzazione.
Collaborazione con i Technical Writer
Il cambiamento più grande al programma Stagione dei documenti nel 2021 ha riguardato il modo in cui i progetti lavoravano con i Technical Writer. Nelle stagioni precedenti, i Technical writer inviavano domanda direttamente a Google e venivano assegnati agli amministratori del programma dei progetti e ricevevano uno stipendio fisso direttamente da Google.
Nel 2021, i Technical writer hanno presentato domanda direttamente ai progetti e hanno fissato il budget per il compenso del Technical writer, con i pagamenti effettuati tramite il Fondo Collettivo aperto Season of Docs.
La maggior parte dei progetti partecipanti al programma del 2021 aveva poca o nessuna esperienza nell'assunzione o nell'assunzione di scrittori tecnici e molti progetti hanno definito questa parte del processo come una che necessita di maggiore supporto. In risposta a questo feedback, il team di Season of Docs ha aggiunto alla guida ai programmi la documentazione per la creazione di contratti per scrittori tecnici.
Consigli per le assunzioni
Ai progetti è stato chiesto di fornire suggerimenti per altri progetti interessati a partecipare alla Season of Docs. I principali consigli sulle assunzioni sono stati:
- Condividi il materiale per la ricerca di personale tecnico il prima possibile, anche prima di essere accettato nel programma. Chiedi alla community di consigliare possibili candidati.
- Condividi su larga scala al di fuori dei canali del progetto. Utilizza un linguaggio inclusivo e incoraggia direttamente i candidati appartenenti a contesti sottorappresentati a presentare domanda.
- Scopri quali strumenti sono essenziali per il processo di creazione della documentazione e recluta scrittori tecnici con esperienza nell'uso di questi strumenti.
- Crea aspettative chiare per il Technical Writer su risultati finali e traguardi, canali di comunicazione e check-in, 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 lo strumento di programmazione tecnica di Season of Docs per offrire mentoring e coaching.
- Dedica più tempo a quello che ti aspetti per l'onboarding dei Technical Writer, per rispondere alle domande e per fornire assistenza durante il programma, soprattutto se questi ultimi non hanno esperienza nel dominio del tuo progetto.
- Documenta la procedura di assunzione, assunzione e onboarding da utilizzare per i progetti futuri.
(Nota: non tutti i progetti indicati nei loro case study in cui sono stati reclutati candidati Technical Writer.)
Problemi comuni nella collaborazione con i Technical Writer
I Technical writer in diversi progetti hanno dovuto ritirarsi 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 mancate corrispondenze di fuso orario o problemi di connessione a internet.
I progetti hanno scoperto che sottovalutavano le difficoltà dell'onboarding nelle comunità o della configurazione della toolchain dei documenti del progetto.
Alcuni progetti hanno subito ritardi nei pagamenti agli autori tecnici a causa di problemi bancari con Open Collective o perché i paesi di origine degli autori avevano delle limitazioni ai pagamenti.
La documentazione del programma relativa alle commissioni di Open Collective non era chiara: Google copriva le commissioni di transazione 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). Lavoreremo per rendere questo aspetto 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. Sono stati inviati tre sondaggi a maggio, agosto e novembre 2022.
Il sondaggio di follow-up ha chiesto ai progetti di confermare che la proposta e i link ai case study fossero ancora attivi. Il sondaggio includeva anche domande sul successo dei loro progetti (come stabilito dalle metriche che hanno impostato nel loro case study), sulla partecipazione continua e sulle retribuzioni dei Technical Writer del progetto:
- Stai ancora lavorando con il Technical writer di Season of Docs?
- Se il tuo Technical writer sta ancora lavorando al tuo progetto, viene retribuito in qualche modo?
- A questo punto, ritieni che il tuo progetto di documentazione vada a buon fine?
Domande future
Come sempre, più impariamo a conoscere la documentazione in open source, più vogliamo saperne di più. Nelle prossime stagioni, ci auguriamo di imparare:
- Se i domini del progetto sono correlati con la scelta del tipo di documento o della metrica
- Quali pratiche di assunzione e inserimento da parte del Technical writer sono più efficaci per il completamento dei progetti e la fidelizzazione del Technical writer
- Tempistica ragionevoli per misurare l'efficacia della documentazione
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.