Fase attuale:
Sviluppo della documentazione. Consulta la cronologia.
Utilizza questo esempio per creare il tuo report sul case study.
PicklePlus: documentare il Glorious Pickle Contribution Tool
Organizzazione o progetto: Glorious Pickle qui il link al sito principale dell'organizzazione o del 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 a forma di cucciolo solitario a container di ravanelli.
Autori: facoltativo: elenca gli autori del case study; utilizza i nomi utente se richiesto
Dichiarazione del problema/astratto 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 è complessa e dispendiosa in termini di tempo; inoltre, lo strumento non dispone di una buona documentazione. Molti collaboratori non hanno esperienza nell'uso di Git o nell'esecuzione di 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 del progetto
Creare la proposta
Come è nata la tua proposta per la stagione di Documenti Google? Quale processo ha utilizzato la tua organizzazione per prendere decisioni in merito a un'idea? Come hai richiesto e incorporato il feedback?
Il Glorious Pickle PickleDocs SIG ha sentito parlare del programma Season of Docs di Google tramite un tweet dell'Open Source Programs Office di Google. I SIG hanno discusso del programma in una riunione bisettimanale e hanno accettato di creare una proposta. Due membri della 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 accettato la bozza della proposta, è stata inviata un'email al progetto più ampio per chiedere feedback. 14 membri della community hanno fornito un feedback, tra cui @GloriouspicklePat, il gestore dell'API che aggiunge gli ingredienti. @GloriouspicklePat si è offerto volontario come risorsa durante il programma.
Dopo aver discusso e incorporato il feedback ricevuto, la proposta è stata inviata al Comitato Direttivo del Glorious Pickle Project per la votazione. Tutti e cinque i membri del 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? Hai speso meno del premio per la donazione? Hai distribuito i fondi correttamente oppure alcune voci che avevi preventivato erano 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 a trovare budget di progetto simili, confrontando il lavoro di proposta in bozza che avevano già svolto. Avevamo anche 1000$rimasti in denaro senza restrizioni per la sponsorizzazione della convention PicklePals del 2019 che abbiamo assegnato al progetto.
A causa di una spesa imprevista, il nostro Technical writer ha affittato un hotspot Wi-Fi, poiché si trovava in un'area colpita da incendi boschivi e ha perso l'accesso a internet nella propria casa. Abbiamo anche inviato ai partecipanti meno t-shirt del previsto, quindi è stato bilanciato.
Inoltre, abbiamo deciso di offrire un compenso a un collaboratore di Glorious Pickle, @Piccalily (che una volta era un editor di copy professionale nella sua vita senza pickle) per aiutare 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 ha svolto? Qualcuno ha abbandonato? Che cosa hai imparato su reclutamento, comunicazione e gestione dei progetti?
Il team principale che ha lavorato a questo progetto era:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (editoriale)
- @GherKen, @VinegarViv (guida per gli amministratori, GPPSC)
- @BBChips, @Glorious PicklePat (esperti in materia)
- Sam Scribe (scrittore tecnico)
Abbiamo trovato Sam Scribe tramite l'elenco del repository GitHub di Google Season of Docs. Abbiamo pensato che la loro esperienza (Sam aveva lavorato per una rivista di culinaria e scritto documentazione per i siti web) fosse adatta al nostro progetto. Sam si è unito alla chiamata bisettimanale di PickleDocs SIG per discutere del progetto con noi, fornendoci 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 di SIG, ma nessuno dei due era disponibile durante la durata del programma.
Poiché il fuso orario di Sam si sovrapponeva solo di poche ore a quello della maggior parte dei membri di PickleDocs SIG, abbiamo inviato una chiamata nel nostro forum di discussione per i selezionatori che si trovavano nel fuso orario di Sam 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 in base alle necessità. @Glorious PicklePat si è anche 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. @GherKen, membro di GPPSC, è intervenuto per gestire le domande amministrative e relative ai pagamenti.
Dopo alcune domande perse (Gloriouspickle utilizza un'istanza senza costi di Slack e occasionalmente la discussione si sposta così velocemente da perdere le conversazioni a causa del limite continuo dell'archivio), abbiamo imparato che dobbiamo tenere un elenco di domande in corso in un documento condiviso (abbiamo usato un documento Google condiviso). I membri dell'evento SIG di PickleDocs lo hanno controllato prima di ogni riunione e si sono assicurati di ricevere 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 Gloriouspickle, è diventato a loro volta un'invincibile raccolta di ricordi.
Sequenza temporale
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 di PickleDocs SIG hanno cercato qualsiasi lavoro precedente che abbiamo ritenuto utile a Sam. Nel corso di un mese, abbiamo trovato alcune note relative a un tentativo precedente di aggiornare la documentazione che si era bloccata, nonché abbiamo esaminato alcune parti dei materiali di controllo della maturità della documentazione nel repository Opendocs di Google.
Una volta ricevuta la buona notizia di essere stati selezionati per la Stagione di Documenti Google, Sam e il SIG di PickleDocs si sono incontrati e hanno elaborato un programma approssimativo:
| Fase | Completato da |
|---|---|
| Rivedi controllo documenti | 7 maggio |
| Casi d'uso dei log di attrito 3 | 14 maggio |
| Esamina i log di attrito con @GloriousChooselePat e @BBChips e rispondi alle query | 28 maggio |
| Prima bozza del caso d'uso aggiornato dei documenti 1 | 25 giugno |
| Bozza del caso d'uso 1 esaminata da @Glorious PicklePat e @KimChiCook | 2 luglio |
| Prima bozza del caso d'uso aggiornato dei documenti 2 | 2 luglio |
| Bozza del caso d'uso 2 esaminata da @GloriouspicklePat e @Dillicious | 9 luglio |
| Prima bozza del caso d'uso aggiornato dei documenti 3 | 9 luglio |
| Bozza del caso d'uso 3 esaminata da @Dillicious e @KimChiCook | 16 luglio |
| Risposta a tutte le query su tutti i casi d'uso | 30 luglio |
| La maggior parte di PickleDocs SIG è andata in vacanza dal 1° al 20 agosto | -- |
| Inizia a testare i nuovi documenti nella community (documenti pubblicati come bozze sul sito Glorious Pickle) | 21 agosto |
| Feedback di test incorporato | 10 settembre |
| Copia e correzione bozza di nuovi documenti | 17 settembre |
| Bozza dello stato dei documenti rimossa, documenti lanciati ufficialmente | 28 settembre |
| Procedura per l'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 un registro di 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 dei risultati finali che non sono stati creati? Elenca anche queste.
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 dei termini appresi da Sam, che è stato pubblicato anche sul sito del progetto Glorious Pickle.
Abbiamo aggiunto al wiki di progetto istruzioni per l'aggiornamento di queste guide illustrative dell'utente.
Avevamo incluso la creazione di una scheda di riferimento per i collaboratori che non avevano mai usato GitHub per aiutarli a usare i nostri processi e strumenti, ma una volta esaminata le risorse disponibili, siamo riusciti a creare il 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 dopo la proposta?
Nella nostra proposta, abbiamo proposto due metriche:
- numero di richieste di pull correlate agli ingredienti
- numero di richieste di pull da nuovi collaboratori
Per il mese di settembre (il primo mese completo dalla pubblicazione della bozza della documentazione) abbiamo registrato un aumento del 5% delle richieste di pull relative agli ingredienti (da 20 di agosto al 21 di settembre) e abbiamo visto tre nuovi collaboratori che hanno inviato 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 totale di collaboratori che hanno fornito più di tre contributi, a partire da ogni trimestre dopo la pubblicazione della documentazione.
Aneddotamente, crediamo che questa nuova documentazione abbia fatto la differenza nel consentire ai nuovi collaboratori di aggiungere elementi al database degli ingredienti di Glorious Pickle, ovvero un nuovo collaboratore menzionato nel commento del loro PR che avevano provato in precedenza, ma che non avevano completato l'aggiornamento perché non comprendevano il processo.
Analisi
Cosa ha funzionato? Che cosa non era previsto? Quali ostacoli o difficoltà hai dovuto affrontare? Ritieni che il tuo progetto sia efficace? Qual è il motivo? Se è troppo presto per dirlo, spiegagli 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à assistito a una certa crescita nel numero di richieste di pull relative agli ingredienti e nel numero di richieste di pull da parte di nuovi collaboratori.
Inoltre, siamo felici che la quasi intera community di Glorious Pickle abbia partecipato, fornendo feedback sulla proposta originale e testando i nuovi documenti in versione bozza.
Abbiamo dovuto affrontare alcuni ostacoli inaspettati e siamo 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; vogliamo augurare a lei e alla sua famiglia il meglio e speriamo di rivederla presto.
Una cosa che non ci siamo resi conto fino a quando Sam ha iniziato a lavorare alla documentazione era la quantità di acronimi e termini correlati al sottaceto che non era familiare a chi partecipasse al nostro progetto senza un background di sottaceto. Sam, però, si è impegnato a tenere un elenco di ogni termine sconosciuto, definendoli attraverso le proprie ricerche e chiedendo ai membri della community di fornire spiegazioni e riferimenti. Questo Glossario di Pickle sarà di grande aiuto per accogliere in futuro altre persone nella comunità del salamoia.
Riepilogo
In 2-4 paragrafi, riassumi la tua esperienza relativa al progetto. Metti in evidenza ciò che hai imparato e cosa sceglieresti di fare in modo diverso in futuro. Che consiglio daresti ad altri progetti che cercano di risolvere un problema simile con la documentazione?
In una parola, la nostra esperienza è stata piccante! Abbiamo raggiunto i risultati della documentazione e le nostre metriche sembrano essere in linea con i nostri obiettivi.
Una parte enorme del successo di questo progetto è stata la fortuna che abbiamo avuto nel lavorare con il nostro Technical Writer, Sam Scribe. [Non l'ho scritto io, Sam] Sebbene Sam non abbia esperienza nel decapaggio o esperienza con GitHub, in qualità di autore tecnico esperto, era a proprio agio nell'immergersi in una nuova area, porre domande e fare ricerche. Sam ha rapidamente preso in considerazione non solo gli strumenti per i progetti (utilizziamo una bacheca Kanban per tenere traccia del lavoro), ma anche le nostre battute! Siamo molto felici che Sam abbia preso il baco del salamoia e che li abbia "imbottigliati" nella nostra community.
Consigliamo ad 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 stimatore con macchinari per il decapaggio industriale e l'abbiamo omessa perché uno dei membri della nostra comunità profondamente coinvolto in 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 occupato Sam!
- Sfrutta le tue reti quando cerchi un Technical Writer. Chiedi dei 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 Gloriouspicklers ha reso facile fare domande.
- Aiuta il tuo Technical Writer a acquisire competenze open source. Sam non aveva mai utilizzato Git prima d'ora, ma dopo aver seguito alcuni tutorial si è reso subito disponibile. All'inizio Sam era preoccupato del numero di 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 vengono affrontati tutti i problemi, ma non necessariamente accontentati") lo ha fatto fiducioso nell'affrontare le critiche utilizzando le sue competenze tecniche di scrittura.
Appendice
Se vuoi aggiungere link ad altri materiali, ad esempio se hai creato un contratto per collaborare con il tuo Technical Writer che vuoi condividere, oppure modelli per il tuo 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 qualsiasi strumento o risorsa di documentazione che hai utilizzato o un punto in cui aggiungere ringraziamenti o ringraziamenti che potrebbero non rientrare nelle sezioni precedenti.
Riconoscimenti
Il nostro team riconosce le seguenti persone e cose:
- @Dillicious vuole ringraziare il suo partner e anche la radio hip hop low-fi
- @KimChiCook vuole ringraziare il suo 할머니 per avergli insegnato a usare i cetrioli in salamoia
- @Piccalily vorrebbe ringraziare il Chicago Manual of Style Online
- @GherKen vorrebbe ringraziare i suoi tre figli per aver mangiato tutti i sottaceti che può preparare
- @VinegarViv vorrebbe ringraziare il resto del team per aver accolto la sua rinuncia
- @BBChips desidera ringraziare il miglior cibo disponibile, i Tunnock's Caramel Wafers
- @GloriousChooselePat vuole ringraziare il SIG di PickleDocs per aver accettato questo progetto
- Sam Scribe desidera ringraziare l'intera community di Glorious Pickle, ma soprattutto i Pickler che hanno inviato loro barattoli per conserve durante la carenza di vasetti dell'estate del 2021, per iniziare la loro strada verso tanti deliziosi sottaceti.