Fase attuale:
Risultati annunciati. 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 la 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 potenziali collaboratori non hanno esperienza con l'utilizzo di Git o con l'invio di richieste 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 di Google? 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 Google 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 di proposta da rivedere durante la 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. Quattordici membri della community hanno fornito un feedback, tra cui @GloriousPicklePat, il maintainer dell'API per l'aggiunta di ingredienti. @GloriousPicklePat si è offerto come volontario come risorsa durante il programma.
Dopo aver discusso e incorporato il feedback ricevuto, la proposta è stata inviata al comitato direttivo del progetto GloriousPickle per la 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 stanziato i fondi correttamente oppure alcuni degli elementi che avevi preventivato erano più/meno/non necessari? Avevi altri fondi al di fuori della stagione dei documenti di Google che hai potuto utilizzare?
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 compensare un collaboratore di GloriousPickle, @Piccalily (che in passato ha lavorato come correttore di bozze professionista nella sua vita non incentrata sui cetrioli) per aiutarci con la correzione e la revisione della documentazione creata dal redattore 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 a pagamento? Quali ruoli ricopriva? Qualcuno ha abbandonato il gioco? 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 (assistenza amministrativa, GPPSC)
- @BBChips, @GloriousPicklePat (esperti in materia)
- Sam Scribe (autore di manuali tecnici)
Abbiamo trovato Sam Scribe nell'elenco del repository GitHub di Google Season of Docs. 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 ha partecipato alla chiamata bisettimanale del SIG PickleDocs e ha parlato del progetto con noi, dando diversi suggerimenti molto utili 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à programma @VinegarViv ha dovuto abbandonare il 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 collaborare con Sam, che, oltre ad aver aggiornato la documentazione di GloriousPickle, è diventato un appassionato di sottaceti.
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 Google Season of Docs, i membri del SIG PickleDocs hanno cercato eventuali lavori precedenti che potevano essere utili a Sam. Nel corso di un mese, abbiamo trovato alcune note di un precedente tentativo di aggiornamento della documentazione che si era interrotto e abbiamo anche esaminato parti dei materiali di controllo dell'idoneità della documentazione nel repo opendocs di Google.
Dopo aver ricevuto la buona notizia che eravamo stati selezionati per la stagione dei documenti di Google, Sam e il gruppo di interesse PickleDocs si sono incontrati e hanno stilato un programma approssimativo:
| Fase | Completato da |
|---|---|
| Controllo della documentazione | 7 maggio |
| Casi d'uso di Friction Log 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 del caso d'uso aggiornato per i documenti 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 ha 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 disponibili. 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 una variante di ingrediente a GloriousPickle
Come aggiornare o correggere un ingrediente in GloriousPickle
Queste guide includevano anche nuovi modelli di richieste di pull per semplificare i contributi.
Inoltre, durante il progetto Sam ha creato un piccolo Glossario dei termini Pickle che ha appreso, 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 un cheat sheet per i collaboratori che non utilizzano GitHub per aiutarli a utilizzare le nostre procedure e i nostri strumenti, ma dopo aver esaminato le risorse disponibili, abbiamo deciso di eseguire il fork del cheat sheet 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 metriche sono cambiate da quando hai presentato la 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 apportato più di tre contributi complessivi, 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 o battute d'arresto hai incontrato? Ritieni che il tuo progetto abbia 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 Google Season of Docs e lo consideriamo un successo. La nuova documentazione è chiara e utile e abbiamo già registrato una crescita nel numero di richieste di pull correlate agli ingredienti e nel numero di richieste di pull da nuovi collaboratori.
Abbiamo anche apprezzato la partecipazione di quasi l'intera community di GloriousPickle, dando feedback sulla proposta originale e testando i nuovi documenti in forma bozza.
Abbiamo dovuto affrontare alcuni ostacoli imprevisti: siamo felici del fatto che gli incendi nello stato di Sam non abbiano causato più danni di un'interruzione del servizio internet! Inoltre, ci è dispiaciuto perdere @VinegarViv dal progetto. Auguriamo a lei e alla sua famiglia il meglio 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 ha tenuto un elenco di tutti i termini non familiari e li ha definiti tramite la propria ricerca 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 tentano di risolvere un problema simile con la documentazione?
In una parola, la nostra esperienza è stata pazzesca! Abbiamo raggiunto i risultati previsti per la documentazione e le nostre metriche sembrano essere in linea con i nostri obiettivi.
Un fattore determinante per il successo di questo progetto è stata la fortuna di collaborare con il nostro Technical Writer, Sam Scribe. [Non ho scritto questo: Sam] Anche se Sam non aveva esperienza nel decapaggio o nell'esperienza con GitHub, in quanto scrittore tecnico esperto, si sentiva a proprio agio ad approfondire un nuovo argomento, a porre domande e a fare ricerche. Sam ha imparato rapidamente non solo a utilizzare i nostri strumenti di progetto (utilizziamo una bacheca Kanban per tenere traccia del lavoro), ma anche le nostre barzellette sui cetrioli. Siamo felici che Sam abbia catturato l'insetto dei sottaceti e li abbiamo "imbottigliati" nella nostra community.
Consigliamo ad altri progetti di:
- Mantieni le proposte brevi 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. Alla fine abbiamo avuto più che abbastanza lavoro per tenere occupato Sam.
- Sfrutta le tue reti quando cerchi un Technical Writer. Chiedi consigli a tutti i membri della tua community. Anche se abbiamo trovato Sam tramite il repository GitHub di Google Season of Docs, ci sentivamo sicuri di collaborare con lui perché avevamo parlato con diverse persone durante il periodo di candidatura.
- Dai il benvenuto al tuo autore tecnico nella tua community. Sam ci ha fatto sapere che l'atteggiamento entusiasta di GloriousPicklers ha reso facile porre domande.
- Aiuta il tuo Technical Writer 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 era preoccupato per la quantità di feedback che avrebbe potuto ricevere dalla community e per come incorporarli, ma il modello di "consenso approssimativo" della nostra community ("si raggiunge il consenso quando tutti i problemi vengono affrontati, ma non necessariamente risolti") lo ha aiutato ad 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 vuole ringraziare i suoi tre figli per aver mangiato tutti i sottaceti che riesce a fare
- @VinegarViv vorrebbe ringraziare il resto del team per averti dato la sua rinuncia
- @BBChips vuole ringraziare il miglior cibo non a base di sottaceti disponibile, i wafer al caramello di Tunnock
- @GloriousPicklePat vorrebbe ringraziare il gruppo di interesse PickleDocs per aver intrapreso 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.