Fase attuale:
il programma della Stagione dei documenti 2021 è terminato il 14 dicembre 2021. Consulta la cronologia.
Utilizza questo esempio per creare il tuo report di case study.
PicklePlus: documentazione dello strumento di contributo GloriousPickle
Organizzazione o progetto: link al sito principale della tua organizzazione o del tuo progetto qui
Descrizione dell'organizzazione: GloriousPickle (versione corrente 1.2.3, prima release nel 2009) è una libreria con licenza MIT per calcolare facilmente la proporzione perfetta di sale, zucchero, aceto e spezie per ogni possibile verdura sott'aceto, in quantità che vanno da un singolo cetriolo solitario a carichi di navi container di ravanelli.
Autori: facoltativo: elenca gli autori del case study; utilizza i nomi utente se richiesto
Problem Statement/Proposal Abstract
Quale problema stavi cercando di risolvere con una documentazione nuova o migliorata? Se possibile, includi un link alla pagina della proposta sul sito del progetto.
L'aggiunta di ingredienti al database di ingredienti dello strumento GloriousPickle è complessa e richiede tempo e lo strumento non dispone di una buona documentazione. Molti aspiranti collaboratori non hanno esperienza nell'utilizzo di Git o nelle richieste di pull. Ciò significa che GloriousPickle presenta gravi lacune nei nostri dati sugli ingredienti e rende il nostro strumento meno utile. Migliorando la documentazione per l'aggiunta di nuovi ingredienti, ci auguriamo di incoraggiare nuovi collaboratori e un aumento delle conserve.
Descrizione del progetto
Creazione della proposta
Come hai ideato la tua proposta per la Stagione dei documenti? Quale procedura ha utilizzato la tua organizzazione per decidere su un'idea? Come hai richiesto e incorporato il feedback?
Il gruppo di interesse PickleDocs di GloriousPickle ha saputo del programma Season of Docs tramite un tweet dell'Ufficio per i programmi open source di Google. Il gruppo di interesse ha discusso del programma durante la riunione bisettimanale e ha accettato di creare una proposta. Due membri del SIG (@KimChiCook e @Dillicious) si sono offerti volontari per lavorare alla bozza della proposta da esaminare nella prossima riunione.
Una volta che il gruppo di interesse PickleDocs ha approvato la bozza della proposta, è stata inviata un'email al progetto più ampio per chiedere un feedback. 14 membri della community hanno offerto un feedback, tra cui @GloriousPicklePat, il gestore dell'API per l'aggiunta degli ingredienti. @GloriousPicklePat si è offerta di essere una risorsa durante il programma.
Dopo aver discusso e integrato i feedback ricevuti, la proposta è stata inviata al comitato direttivo del progetto GloriousPickle per una votazione. Tutti e cinque i membri del GPPSC hanno votato a favore dell'invio della proposta e della domanda e @VinegarViv ha accettato di aiutarci a creare l'account Open Collective necessario per partecipare al programma e supervisionare i pagamenti.
Budget
Includi una breve sezione sul budget. Come hai stimato il lavoro? Ci sono state spese impreviste? Alla fine hai speso meno del premio per la concessione? Hai potuto utilizzare altri fondi al di fuori della Stagione dei documenti?
Due membri del gruppo di interesse GloriousPickle PickleDocs hanno lavorato come technical writer (uno in Europa e uno in Argentina). Ci hanno aiutato a stimare il lavoro e a trovare budget di progetti simili, confrontando la bozza della proposta che avevano già realizzato. Inoltre, avevamo 1000$di fondi per sponsorizzazioni non soggetti a restrizioni provenienti dal nostro convegno PicklePals del 2019, che abbiamo assegnato al progetto.
Una spesa imprevista è stata l'aiuto al nostro autore tecnico per l'affitto di un hotspot Wi-Fi, in quanto si trovava in un'area interessata da incendi boschivi e aveva perso l'accesso a internet a casa. Inoltre, abbiamo finito per inviare ai partecipanti meno t-shirt del previsto, quindi è andata bene.
Inoltre, abbiamo deciso di risarcire una persona che lavora a GloriousPickle, @Piccalily (che in passato era un copyeditor professionista nella sua vita da solista) per aiutarle con il copy editing e la correzione di bozze della documentazione creata dall'autore tecnico.
Partecipanti
Chi ha lavorato a questo progetto (utilizza i nomi utente se richiesto dai partecipanti)? Come hai trovato e assunto il tuo Technical Writer? Come hai trovato altri volontari o partecipanti pagati? Quali ruoli aveva? Qualcuno si è ritirato? Che cosa hai imparato su reclutamento, comunicazione e gestione dei progetti?
Il team principale che lavorava a questo progetto era:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (redattrice)
- @GherKen, @VinegarViv (aiuto amministratore, GPPSC)
- @BBChips, @GloriousPicklePat (esperti in materia)
- Sam Scribe (autore di manuali tecnici)
Abbiamo trovato Sam Scribe nell'elenco del repository GitHub della stagione di Documenti. Abbiamo pensato che la loro esperienza (Sam aveva lavorato per una rivista di cucina e scritto la documentazione per i siti web) corrispondeva al nostro progetto. Sam si è unito alla chiamata bisettimanale del SIG di PickleDocs e ci ha parlato del progetto, fornendo diversi suggerimenti molto preziosi che abbiamo incorporato nella proposta. Abbiamo anche contattato altri due autori tecnici che conosciamo tramite le reti dei membri del nostro SIG, ma nessuno dei due era disponibile durante il periodo di tempo del programma.
Poiché il fuso orario di Sam si sovrappone di poche ore alla maggior parte dei membri del gruppo di interesse PickleDocs, abbiamo inviato un appello nel nostro forum di discussione per i collaboratori che si trovavano nel fuso orario di Sam e che conoscevano la procedura di aggiunta degli ingredienti. @BBChips si è offerta di rispondere alle domande di Sam e di aiutarlo a trovare altri esperti, se necessario. @GloriousPicklePat si è anche offerto di aiutare Sam a comprendere l'architettura sottostante dello strumento e i possibili messaggi di errore dell'API, oltre a fornire assistenza per GitHub e Git.
Purtroppo, a metà del programma, @VinegarViv ha dovuto fare un passo indietro dal progetto per motivi personali. Il membro del GPPSC @GherKen si è offerto di gestire le domande amministrative e di pagamento.
Dopo alcune domande perse (GloriousPickle utilizza un'istanza Slack senza costi e a volte la discussione procede così rapidamente che perdiamo le conversazioni a causa del limite di archiviazione progressivo), abbiamo imparato che dobbiamo tenere un elenco delle domande in esecuzione in un documento condiviso (abbiamo utilizzato un documento Google condiviso). I membri del SIG di PickleDocs lo controllavano prima di ogni riunione e si assicuravano di ricevere le risposte prima della fine della riunione. Sam è riuscito a contattare direttamente @BBChips per domande urgenti.
Siamo stati molto felici di lavorare con Sam e Sam, oltre ad aggiornare la documentazione di GloriousPickle, è diventato loro stessi un accanito cetriolo!
Cronologia
Fornisci una breve panoramica della sequenza temporale del progetto (indica la data di fine stimata o le tappe intermedie se il progetto è in corso).
Mentre attendevamo l'annuncio delle organizzazioni partecipanti al programma Season of Docs, i membri del gruppo di interesse PickleDocs hanno cercato eventuali lavori precedenti che potevano essere utili a Sam. Nel corso di un mese, abbiamo trovato alcune note relative a un precedente tentativo di aggiornamento della documentazione che si era bloccata e abbiamo anche analizzato parti dei materiali per la verifica della maturità della documentazione nel repository di Google Opendocs.
Dopo aver ricevuto la buona notizia che il nostro progetto è stato selezionato per la Stagione dei documenti 2021, Sam e il gruppo di interesse PickleDocs si sono incontrati e hanno stilato un programma approssimativo:
| Fase | Completato da |
|---|---|
| Controllare l'audit dei documenti | 7 maggio |
| Casi d'uso del log delle difficoltà 3 | 14 maggio |
| Esamina i log relativi ai problemi con @GloriousPicklePat e @BBChips, rispondi alle query | 28 maggio |
| Prima bozza del caso d'uso 1 relativo ai documenti aggiornati | 25 giugno |
| Bozza del caso d'uso 1 recensito da @GloriousPicklePat e @KimChiCook | 2 luglio |
| Prima bozza dei documenti aggiornati - caso d'uso 2 | 2 luglio |
| Bozza del caso d'uso 2 esaminata da @GloriousPicklePat e @Dillicious | 9 luglio |
| Prima bozza del caso d'uso relativo ai documenti aggiornati 3 | 9 luglio |
| Bozza del caso d'uso 3 esaminata da @Dillicious e @KimChiCook | 16 luglio |
| Tutte le domande hanno una risposta in tutti i casi d'uso | 30 luglio |
| La maggior parte del gruppo di interesse PickleDocs era in vacanza dal 1° all'20 agosto | -- |
| Iniziare i test dei nuovi documenti nella community (documenti pubblicati come bozze sul sito GloriousPickle) | 21 agosto |
| Feedback del test incorporati | 10 settembre |
| Copia e correzione bozza di nuovi documenti | 17 settembre |
| Stato della bozza di documenti rimossi, documenti lanciati ufficialmente | 28 settembre |
| Procedura per aggiornare la documentazione creata | 1 novembre |
| Questo case study è stato creato | 8 novembre |
| Case study inviato | 16 novembre |
Nel budget della proposta avevamo stimato che il redattore tecnico avrebbe dedicato 10-15 ore a settimana al nostro progetto. Sam ha tenuto traccia del tempo trascorso e ha registrato una media di 11,5 ore a settimana.
Risultati
Che cosa è stato creato, aggiornato o modificato in altro modo? Includi i link alla documentazione pubblicata, se disponibile. Ci sono elementi della proposta che non sono stati creati? Elenca anche queste.
Sono stati documentati tre casi d'uso principali con guide dettagliate per gli utenti:
Come aggiungere un nuovo ingrediente a GloriousPickle
Come aggiungere un ingrediente della variante a GloriousPickle
Come aggiornare o correggere un ingrediente in GloriousPickle
Queste guide includevano anche nuovi modelli di richieste pull per semplificare i contributi.
Inoltre, durante il progetto Sam ha creato un piccolo glossario di termini relativi ai cetrioli che ha imparato, che è stato pubblicato anche sul sito del progetto GloriousPickle.
Abbiamo aggiunto istruzioni per aggiornare queste guide pratiche per gli utenti alla wiki del progetto.
Avevamo incluso la creazione di una scheda di riferimento per i collaboratori che non conoscevano GitHub per aiutarli a utilizzare i nostri processi e strumenti, ma una volta esaminate le risorse disponibili, siamo stati in grado di creare la scheda di riferimento di un altro progetto.
Metriche
Quali metriche hai scelto per misurare il successo del progetto? Hai potuto raccogliere queste metriche? Le metriche hanno mostrato una buona o scarsa correlazione con i risultati che volevi ottenere per il progetto? Le tue metriche sono cambiate dalla tua proposta?
Nella nostra proposta abbiamo proposto due metriche:
- numero di richieste pull relative agli ingredienti
- numero di richieste pull da parte di nuovi collaboratori
Nel mese di settembre (il primo mese completo dalla pubblicazione della bozza della documentazione), abbiamo registrato un aumento del 5% delle richieste pull relative agli ingredienti (da 20 ad agosto a 21 a settembre) e tre nuovi collaboratori che hanno inviato in totale quattro richieste pull (rispetto a due nuovi collaboratori che hanno inviato due richieste pull ad agosto). Abbiamo intenzione di monitorare queste metriche su base mensile.
A partire dal 1° gennaio, monitoreremo anche il numero di collaboratori che hanno dato in totale più di tre contributi, a partire dal trimestre successivo alla pubblicazione della documentazione.
Anecdotally, we believe this new documentation has made a difference in enabling new contributors to add to the GloriousPickle ingredient database—one new contributor mentioned in the comment of their PR that they had tried before but hadn't completed their update because they didn't understand the process.
Analisi
Che cosa ha funzionato? Cosa non era previsto? Quali ostacoli hai dovuto affrontare? Consideri il tuo progetto un successo? Qual è il motivo? (se è troppo presto per dirlo, spiega quando pensi di poter valutare il successo del tuo progetto).
Siamo molto soddisfatti del risultato del nostro progetto Season of Docs e lo consideriamo un successo. La nuova documentazione è chiara e utile e abbiamo già registrato un aumento del numero di pull request relative agli ingredienti e del numero di pull request inviate da nuovi collaboratori.
Siamo stati anche felici che quasi tutta la community di GloriousPickle abbia partecipato, fornendo feedback sulla proposta originale e testando i nuovi documenti in forma di bozza.
Abbiamo dovuto affrontare alcuni ostacoli imprevisti, ma siamo stati fortunati che gli incendi boschivi nello stato di Sam non abbiano causato danni maggiori di un'interruzione di internet. Inoltre, ci dispiace aver perso @VinegarViv dal progetto; auguriamo il meglio a lei e alla sua famiglia e speriamo di rivederla presto.
Una cosa che non abbiamo capito finché Sam non ha iniziato a lavorare alla documentazione è quanti termini e acronimi correlati a Pickle non sarebbero stati familiari a chi si avvicina al nostro progetto senza esperienza in materia. Tuttavia, Sam si è proposto di tenere un elenco di tutti i termini poco familiari e di definirli attraverso ricerche personali e chiedendo spiegazioni e riferimenti ai membri della community. Questo glossario dei sottaceti sarà di grande aiuto per accogliere più persone nella community dei sottaceti in futuro.
Riepilogo
Riassumi la tua esperienza con il progetto in 2-4 paragrafi. Metti in evidenza ciò che hai imparato e cosa sceglieresti di fare in modo diverso in futuro. Che consiglio daresti ad altri progetti che stanno cercando di risolvere un problema simile con la documentazione?
In una parola, la nostra esperienza è stata fantastica. Abbiamo raggiunto i risultati previsti per la documentazione e le nostre metriche sembrano essere in linea con i nostri obiettivi.
Una parte enorme del successo di questo progetto è stata la fortuna di lavorare con il nostro scrittore tecnico Sam Scribe. [Non ho scritto questo testo, Sam] Sebbene Sam non avesse esperienza con GitHub o con il pickling, come Technical Writer esperto non aveva problemi a immergersi in un nuovo argomento, a porre domande e a fare ricerche. Sam ha imparato rapidamente non solo agli strumenti per i progetti (usiamo una lavagna kanban per tenere traccia del lavoro), ma anche alle nostre battute sul sottaceto. Siamo molto felici che Sam abbia preso il vizio di fare i sottaceti e che lo abbiamo "inseminato" nella nostra community.
Consigliamo agli altri progetti di:
- Fai in modo che le tue proposte siano piccole e gestibili. Inizialmente volevamo includere nella nostra proposta la documentazione per l'utilizzo del nostro estimatore con le macchine per l'inscatolamento industriale dei sottaceti, ma l'abbiamo omessa perché uno dei membri della nostra community profondamente coinvolto nella realizzazione di macchine per l'inscatolamento dei sottaceti open source avrebbe dovuto scrivere la sua tesi di dottorato durante il programma. Abbiamo finito per fare molto lavoro per tenere Sam occupato.
- Sfrutta le tue reti quando cerchi un Technical Writer. Chiedi consigli a tutti i membri della community. Anche se abbiamo trovato Sam tramite GitHub di Season of Docs, ci sentivamo sicuri di lavorare con lui perché avevamo parlato con diverse persone durante il periodo di candidatura.
- Dai il benvenuto al tuo Technical Writer nella tua community. Sam ci ha fatto sapere che l'atteggiamento entusiasta di GloriousPicklers ha reso facile porre domande.
- Aiuta il tuo autore di manuali tecnici ad acquisire competenze open source. Sam non aveva mai utilizzato git prima, ma dopo aver seguito alcuni tutorial ha imparato rapidamente a utilizzarlo. All'inizio Sam si preoccupava del feedback che avrebbe potuto ricevere dalla community e di come incorporarli, ma il modello di "consenso approssimativo" della nostra community ("il consenso si ottiene quando tutti i problemi sono stati affrontati, ma non necessariamente adeguati") lo ha fatto confidare nell'affrontare le critiche utilizzando le sue competenze di scrittura tecnica.
Appendice
Se hai altri materiali da collegare (ad esempio, se vuoi condividere un contratto per collaborare con il tuo Technical Writer), oppure modelli per il progetto di documentazione o altre risorse di documentazione aperte, puoi elencarli e collegarli qui. L'appendice è anche un buon posto per elencare i link a eventuali strumenti o risorse di documentazione che hai utilizzato oppure per aggiungere ringraziamenti o riconoscimenti che potrebbero non rientrare nelle sezioni precedenti.
Riconoscimenti
Il nostro team vuole ringraziare le seguenti persone e risorse:
- @Dillicious vuole ringraziare il suo partner e anche la radio hip hop low-fi
- @KimChiCook ringrazia la sua 할머니 per avergli insegnato a sottaceto
- @Piccalily vuole ringraziare il Chicago Manual of Style Online
- @GherKen ringrazia i suoi tre figli per aver mangiato tutti i sottaceti che può preparare
- @VinegarViv vuole ringraziare il resto del team per aver accettato le sue dimissioni
- @BBChips vuole ringraziare il miglior cibo non a base di sottaceti disponibile, i wafer al caramello di Tunnock
- @GloriousPicklePat desidera ringraziare il SIG di PickleDocs per aver partecipato a questo progetto
- Sam Scribe vuole ringraziare l'intera community di GloriousPickle, ma in particolare i Pickler che gli hanno inviato barattoli per conserve durante la carenza di barattoli dell'estate 2021, dando inizio alla produzione di molti deliziosi sottaceti.