Fase attuale:
Risultati annunciati. Consulta la cronologia.
Usa questo esempio per creare il tuo report sul case study.
PicklePlus: documentazione sullo strumento di contributo Glorious Pickle
Organizzazione o progetto: Glorious Pickle inserisci qui il link al sito principale della tua organizzazione o del tuo progetto
Descrizione dell'organizzazione: Glorious Pickle (versione corrente 1.2.3, prima release nel 2009) è una libreria con licenza MIT per calcolare facilmente il rapporto perfetto tra sale, zucchero, aceto e spezie per ogni possibile ortaggio sottaceto, in quantità che vanno da un singolo cetriolo solitario a piccole quantità di ravanelli.
Autori: facoltativo: elenca gli autori del case study; utilizza i nomi utente se richiesto
Dichiarazione del problema/estratto della proposta
Quale problema stavi cercando di risolvere con una documentazione nuova o migliorata? Se possibile, inserisci un link alla pagina della proposta sul sito del tuo progetto.
L'aggiunta di ingredienti al database degli ingredienti dello strumento Glorious Pickle è un'operazione complicata e dispendiosa in termini di tempo; inoltre, lo strumento non dispone di una buona documentazione. Molti aspiranti collaboratori non hanno esperienza nell'uso di Git o nelle richieste di pull. Ciò significa che Glorious Pickle presenta gravi lacune nei dati degli ingredienti e rende il nostro strumento meno utile. Migliorando la documentazione per l'aggiunta di nuovi ingredienti, ci auguriamo di incoraggiare nuovi collaboratori e più sottaceti.
Descrizione progetto
Creare la proposta
Come hai elaborato la tua proposta per la stagione di Documenti Google? Quale processo ha utilizzato la tua organizzazione per decidere su un'idea? Come hai richiesto e incorporato il feedback?
Il gruppo SIG Glorious Pickle PickleDocs ha sentito parlare del programma Google Season of Docs grazie a un tweet dell'ufficio Open Source Programs di Google. Il gruppo SIG ha discusso del programma in una 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 esaminare nel corso della prossima riunione.
Una volta che il SIG di PickleDocs ha concordato la bozza della proposta, è stata inviata un'email al progetto più ampio per chiedere un feedback. 14 membri della community hanno offerto il proprio feedback, tra cui @Glorious PicklePat, il gestore dell'API per l'aggiunta degli ingredienti. @Glorious PicklePat si è offerto volontariamente come risorsa durante il programma.
Dopo aver discusso e recepito il feedback ricevuto, la proposta è stata inviata al comitato direttivo del progetto Glorious Pickle per la votazione. Tutti e cinque i membri della GPPSC hanno votato +1 per l'invio della proposta e della domanda e @VinegarViv ha accettato di contribuire alla creazione dell'account Open Collective necessario per partecipare al programma e supervisionare i pagamenti.
Budget
Includi una breve sezione sul tuo budget. Come hai valutato il lavoro? Ci sono state spese impreviste? Alla fine, hai speso meno del premio per la concessione di una concessione? Hai stanziato i fondi correttamente oppure c'erano alcune voci che avevi previsto in più/meno/non necessarie? Avevi altri fondi oltre alla Stagione di Documenti Google che hai potuto utilizzare?
Due membri del Glorious Pickle PickleDocs SIG hanno lavorato come Technical Writer (uno in Europa e uno in Argentina). Ci hanno aiutato a stimare il lavoro e trovare budget di progetto simili, confrontando le bozze del lavoro di proposta che avevano fatto prima. Avevamo anche 1000$rimasti in denaro senza restrizioni per la sponsorizzazione del nostro convegno PicklePals del 2019 che abbiamo assegnato al progetto.
Una spesa imprevista è stata quella di aiutare il nostro Technical writer ad affittare un hotspot Wi-Fi, dato che si trovava in un'area colpita da incendi boschivi e perdendo l'accesso a internet nella propria casa. Abbiamo anche finito di inviare ai partecipanti meno t-shirt del previsto, quindi è stato bilanciato.
Inoltre, abbiamo deciso di risarcire un collaboratore di Glorious Pickle, @Piccalily (che in passato era un copyeditor professionista nella sua vita senza pickle) per aiutarlo con il copyediting e la correzione di bozze della documentazione creata dal Technical writer.
Partecipanti
Chi ha lavorato a questo progetto (utilizza i nomi utente se richiesti dai partecipanti)? Come hai trovato e assunto il tuo Technical Writer? Come hai trovato altri volontari o partecipanti paganti? Quali ruoli hanno avuto? Qualcuno ha abbandonato il sito? 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 (editor dei testi)
- @GherKen, @VinegarViv (assistenza amministrativa, GPPSC)
- @BBChips, @Glorious PicklePat (esperti in materia)
- Sam Scribe (writer tecnico)
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 aveva scritto documentazione per i siti web) corrispondesse bene al nostro progetto. Sam si è unito alla chiamata bisettimanale SIG di PickleDoc e ha parlato con noi del progetto, dandoci diversi suggerimenti molto preziosi che abbiamo incorporato nella proposta. Abbiamo anche contattato altri due Technical Writer noti a noi attraverso le reti dei nostri membri SIG, ma nessuno dei due era disponibile durante il periodo di tempo del programma.
Poiché il fuso orario di Sam si sovrapponeva solo di poche ore alla maggior parte dei membri del SIG di PickleDocs, abbiamo inviato una chiamata al nostro forum di discussione per i Pickler che si trovavano nel fuso orario di Samuele e conoscevano il processo di aggiunta degli ingredienti. @BBChips si è offerto volontario per rispondere alle domande per Sam e per aiutarlo a trovare altri esperti, se necessario. Inoltre, @Glorious PicklePat si è offerto volontario per 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.
Sfortunatamente, a metà del programma @VinegarViv ha dovuto abbandonare il progetto per motivi personali. Il membro di GPPSC @GherKen è intervenuto per gestire le domande amministrative e relative ai pagamenti.
Dopo alcune domande mancate (Glorious Pickle utilizza un'istanza di Slack senza costi e occasionalmente la discussione si sposta così velocemente da perdere le conversazioni a causa del limite di archiviazione in sequenza), abbiamo imparato che dobbiamo tenere un elenco delle domande in esecuzione in un documento condiviso (abbiamo usato un documento Google condiviso). I membri del SIG di PickleDocs lo hanno controllato prima di ogni riunione e si sono assicurati di ottenere le risposte prima della fine della riunione. Sam è riuscito a inviare un ping direttamente a @BBChips per domande urgenti.
Siamo stati molto felici di lavorare con Sam e Sam, oltre ad aggiornare la documentazione di Glorious Pickle, è diventato loro stessi un accanito raccoglitore.
Sequenza
Fornisci una breve panoramica delle tempistiche del progetto (indica la data di fine stimata o gli obiettivi intermedi se il progetto è in corso).
Mentre aspettavamo che il programma Google Season of Docs annunciasse le organizzazioni partecipanti, i membri del SIG di PickleDocs hanno cercato qualsiasi lavoro precedente che pensavamo potesse essere utile per Sam. Nel corso di un mese, abbiamo trovato alcune note di un precedente tentativo di aggiornare la documentazione che si era interrotta e abbiamo anche esaminato alcune parti dei materiali di controllo della maturità della documentazione nel repository Opendocs di Google.
Dopo che abbiamo ricevuto la buona notizia che siamo stati selezionati per la stagione di Documenti Google, Sam e il sig di PickleDocs si sono incontrati e hanno elaborato un programma difficile:
| Palcoscenico | Completato da |
|---|---|
| Rivedi controllo documenti | 7 maggio |
| Casi d'uso del log di attrito 3 | 14 maggio |
| Esamina i log di attrito con @Glorious PicklePat e @BBChips e rispondi alle query | 28 maggio |
| Prima bozza del caso d'uso 1 di documenti aggiornati | 25 giugno |
| Bozza del caso d'uso 1 esaminata da @Glorious PicklePat e @KimChiCook | 2 luglio |
| Prima bozza del caso d'uso 2 di documenti aggiornati | 2 luglio |
| Bozza del caso d'uso 2 esaminata da @Glorious PicklePat e @Dillicious | 9 luglio |
| Prima bozza del caso d'uso di documenti aggiornati 3 | 9 luglio |
| Bozza del caso d'uso 3 esaminata da @Dillicious e @KimChiCook | 16 luglio |
| Risposte a tutte le query per tutti i casi d'uso | 30 luglio |
| La maggior parte di PickleDoc SIG è andata in vacanza dal 1° al 20 agosto | -- |
| Inizia a testare i nuovi documenti nella community (documenti pubblicati come bozze sul sito di Glorious Pickle) | 21 agosto |
| Feedback del test incorporato | 10 settembre |
| Correzione e correzione bozza dei nuovi documenti | 17 settembre |
| Bozza dello stato dei documenti rimossa, documenti lanciati ufficialmente | 28 settembre |
| Procedura di aggiornamento della documentazione creata | 1 novembre |
| Questo case study è stato creato | 8 novembre |
| Case study inviato | 16 novembre |
Nel budget della proposta avevamo stimato che il Technical Writer avrebbe dedicato 10-15 ore alla settimana a lavorare al nostro progetto. Sam ha tenuto i registri 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. La proposta conteneva risultati finali che non sono stati creati? Elenca anche queste informazioni.
Tre casi d'uso principali sono stati documentati con guide illustrative complete per l'utente:
Come aggiungere un nuovo ingrediente a Glorious Pickle
Come aggiungere una variante di ingrediente a Glorious Pickle
Come aggiornare o correggere un ingrediente in Glorious Pickle
Queste guide includevano anche nuovi modelli di richieste di pull per semplificare i contributi.
Inoltre, durante il progetto Sam ha creato un piccolo glossario Pickle dei termini appresi, pubblicato anch'esso sul sito del progetto Glorious Pickle.
Abbiamo aggiunto al wiki del progetto le istruzioni per aggiornare queste guide illustrative per l'utente.
Avevamo incluso la creazione di una scheda di riferimento per i collaboratori che non conoscevano GitHub per aiutarli a utilizzare i nostri processi e i nostri strumenti, ma dopo aver esaminato le risorse disponibili siamo riusciti a creare un fork della 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 sono correlate in modo soddisfacente o insoddisfacente ai risultati auspicati per il progetto? Le metriche sono cambiate dalla tua proposta?
Nella nostra proposta, abbiamo proposto due metriche:
- numero di richieste di pull relative agli ingredienti
- numero di richieste di pull dai nuovi collaboratori
Per il mese di settembre (il primo mese intero dalla pubblicazione della bozza della documentazione) abbiamo registrato un aumento del 5% delle richieste di pull relative agli ingredienti (dal 20 di agosto al 21 di settembre) e abbiamo visto tre nuovi collaboratori che hanno effettuato quattro richieste di pull totali (rispetto a due nuovi collaboratori che hanno effettuato due richieste di pull ad agosto). Prevediamo di monitorare queste metriche su base mensile.
A partire dal 1° gennaio, terremo inoltre traccia del numero complessivo di collaboratori che hanno fornito più di tre contributi, a partire da ogni trimestre dopo la pubblicazione della documentazione.
Aneddoticamente, crediamo che questa nuova documentazione abbia fatto la differenza nel consentire ai nuovi collaboratori di aggiungere elementi al database degli ingredienti di Glorious Pickle: un nuovo collaboratore menzionato nel commento del suo PR che aveva provato in precedenza, ma che non avevano completato l'aggiornamento perché non comprendevano la procedura.
Analisi
Cosa è andato bene? Che cosa non era previsto? Quali ostacoli o difficoltà hai dovuto affrontare? Ritieni che il tuo progetto sia riuscito? Perché o perché no? (Se è troppo presto per dirlo, spiegagli quando ti aspetti di poter giudicare il successo del progetto.)
Siamo molto soddisfatti del risultato del nostro progetto per la stagione dei documenti Google e lo consideriamo un successo. La nuova documentazione è chiara e utile e abbiamo già assistito a una certa crescita del numero di richieste di pull relative agli ingredienti e del numero di richieste di pull da parte dei nuovi collaboratori.
Siamo inoltre soddisfatti del fatto che quasi l'intera community di Glorious Pickle abbia partecipato, fornendo feedback sulla proposta originale e testando i nuovi documenti in forma di bozza.
Abbiamo dovuto affrontare alcuni ostacoli imprevisti: eravamo grati che gli incendi nello stato di Sam non abbiano causato più danni di un'interruzione della connessione a internet. Inoltre, siamo stati dispiaciuti per la perdita di @VinegarViv dal progetto. Auguriamo il meglio a lei e alla sua famiglia e speriamo di rivederla presto.
Una cosa che non ci siamo resi conto fino a quando Sam ha iniziato a lavorare alla documentazione era il numero di acronimi e termini correlati al sottaceto che non conoscevano qualcuno che entrava nel nostro progetto senza alcuna esperienza in salamoia. Tuttavia, Sam si è impegnato a scrivere un elenco di tutti i termini sconosciuti e li ha definiti attraverso le proprie ricerche e chiedendo spiegazioni e riferimenti ai membri della comunità. Questo Glossario di Pickle sarà di grande aiuto per accogliere più persone nella comunità dei sottaceti in futuro.
Riepilogo
Descrivi in 2-4 paragrafi la tua esperienza con il progetto. Metti in evidenza ciò che hai imparato e cosa sceglieresti di fare in modo diverso in futuro. Quale consiglio daresti ad altri progetti che cercano di risolvere un problema simile con la documentazione?
In una parola, la nostra esperienza è stata stravagante! Abbiamo raggiunto i nostri risultati di documentazione e le nostre metriche sembrano essere in linea con i nostri obiettivi.
Una parte importante del successo di questo progetto è stata la fortuna che abbiamo avuto nel lavorare con il nostro Technical Writer, Sam Scribe. [Non ho scritto questo - Sam] Sebbene Sam non avesse esperienza in salamoia o esperienza con GitHub, in qualità di autore tecnico esperto, era a proprio agio nel tuffarsi in una nuova area, porre domande e fare ricerche. Sam ha rapidamente accolto non solo gli strumenti del progetto (utilizziamo una lavagna kanban per tenere traccia del lavoro), ma anche le nostre battute. Siamo molto felici che Sam abbia catturato il cimice per il sottaceto e che li abbiamo "imbottigliati" nella nostra community.
Consigliamo ad altri progetti di:
- Fai in modo che le tue proposte siano piccole e gestibili. All'inizio volevamo includere nella nostra proposta la documentazione relativa all'utilizzo del nostro stimatore con macchinari per il decapaggio industriale, ma l'abbiamo tralasciata perché uno dei membri della nostra comunità profondamente coinvolti nei macchinari per sottaceti open source stava per scrivere la sua tesi di dottorato durante il programma.) Abbiamo finito per avere più che sufficiente per tenere impegnato Sam.
- Sfrutta le tue reti quando cerchi un Technical Writer. Chiedi consigli a tutti i membri della community. Anche se abbiamo trovato Sam tramite il GitHub di Google Season of Docs, ci siamo sentiti sicuri perché abbiamo parlato con diverse persone durante il periodo della candidatura.
- Dai il benvenuto al tuo Technical Writer nella tua community. Sam ci ha fatto sapere che l'atteggiamento entusiasta dei Glorious Picklers ha reso facile fare domande.
- Aiuta il tuo Technical Writer ad acquisire competenze open source. Sam non aveva mai usato Git prima, ma dopo aver seguito alcuni tutorial sono diventati rapidamente operativi. All'inizio Sam era preoccupato di quanti feedback avrebbero potuto ricevere dalla community e di come incorporarli, ma il modello di "consenso approssimativo" della nostra community ("consenso si ottiene quando tutte le questioni vengono affrontate, ma non necessariamente accolte") lo ha reso fiducioso nell'affrontare le critiche avvalendosi delle sue competenze di scrittura tecnica.
Appendice
Se hai altri materiali a cui vuoi collegarti (ad esempio, se hai creato un contratto per lavorare con il tuo Technical Writer che vuoi condividere, modelli per il tuo progetto di documentazione o altre risorse di documentazione aperte, puoi elencarli e collegarli qui). Inoltre, l'Appendice è utile per elencare i link a eventuali risorse o strumenti di documentazione che hai utilizzato oppure in cui aggiungere ringraziamenti o ringraziamenti che potrebbero non rientrare nelle sezioni precedenti.
Attestazioni
Il nostro team desidera ringraziare le seguenti persone e cose:
- @Dillicious ringrazia il suo partner e anche la radio hip hop low-fi
- @KimChiCook vuole ringraziare il suo 할머수 per avergli insegnato a usare il cetriolo
- @Piccalily desidera ringraziare il Chicago Manual of Style Online
- @GherKen vorrebbe ringraziare i suoi tre figli per aver mangiato tutti i sottaceti che riesce a preparare
- @VinegarViv vuole ringraziare il resto del team per aver accolto la sua rinuncia
- @BBChips desidera ringraziare il miglior cibo non disponibile: i wafer al caramello di Tunnock
- @Glorious PicklePat desidera ringraziare il PickleDocs SIG per aver partecipato a questo progetto
- Sam Scribe desidera ringraziare l'intera community di Glorious Pickle, ma soprattutto i Pickler che hanno inviato loro vasetti per l'inscatolamento durante la carenza di barattoli dell'estate del 2021, facendoli iniziare sulla strada di molti deliziosi sottaceti!