Obecna faza:
ogłoszono wyniki. Zobacz oś czasu.
Na podstawie tego przykładu możesz utworzyć własny raport ze studium przypadku.
PicklePlus: dokumentowanie narzędzia do przesyłania danych GloriousPickle
Organizacja lub projekt: Glorious Pickle link do głównej witryny organizacji lub projektu
Opis organizacji: GloriousPickle (obecna wersja 1.2.3, pierwsza wersja z 2009 r.) to biblioteka w licencjach MIT, która ułatwia obliczanie idealnych proporcji soli, cukru, octu i przypraw do każdego możliwego warzywa nadającego się do ukiszenia, w ilościach od pojedynczego małego ogórka po rzepę w kontenerze.
Autorzy: opcjonalnie: podaj autorów studium przypadku; w razie potrzeby użyj nazw użytkowników.
Omówienie problemu/propozycji
Jaki problem próbujesz rozwiązać za pomocą nowej lub ulepszonej dokumentacji? Link do strony z ofertą na stronie projektu (jeśli to możliwe).
Dodawanie składników do bazy danych składników narzędzia GloriousPickle jest czasochłonne i skomplikowane, a narzędzie nie ma dobrej dokumentacji. Wielu potencjalnych współtwórców nie ma doświadczenia w korzystaniu z gita ani tworzenia pull requestów. Oznacza to, że w danych o składnikach GloriousPickle ma poważne luki, a narzędzie jest mniej przydatne. Poprawiając dokumentację dotyczącą dodawania nowych składników, mamy nadzieję zachęcić nowych autorów do tworzenia przepisów i zwiększać liczbę przepisów na ogórki konserwowe.
Opis projektu
Tworzenie propozycji
Jak powstała propozycja Google Season of Docs? Jaki proces zastosowała Twoja organizacja, aby podjąć decyzję dotyczącą pomysłu? Jak zbierasz i uwzględniasz opinie?
Organizacja GloriousPickle PickleDocuments SIG dowiedział się o programie Season of Dokumenty z tweeta w biurze Google Open Source Programs Office. Grupa SIG omówiła program na spotkaniu odbywającym się co 2 tygodnie i postanowiła przedstawić propozycję. Dwóch członków zespołu SIG (@KimChiCook i @Dillicious) zaoferowało się, że przygotuje projekt propozycji do sprawdzenia na następnym spotkaniu.
Gdy grupa zainteresowań PickleDocs uzgodniła projekt propozycji, wysłano e-maila do szerszego grona uczestników projektu z prośbą o opinię. Członkowie społeczności, w tym @GloriousPicklePat, który utrzymuje interfejs API do dodawania składników, przekazali 14 opinii. @GloriousPicklePat zgłosił się na ochotnika, aby udzielać porad w trakcie programu.
Po omówieniu i uwzględnieniu otrzymanych opinii przekazano ją komitetowi sterującemu projektu GloriousPickle do głosowania. Wszyscy 5 członków GPPSC głosowało za przesłaniem propozycji i wniosku, a @VinegarViv zgodził się pomóc w utworzniu konta Open Collective, które jest wymagane do udziału w programie i nadzorowania płatności.
Budżet
Wprowadź krótki rozdział dotyczący budżetu. Jak oszacowałeś/oszacowałaś pracę? Czy wystąpiły jakieś nieoczekiwane wydatki? Czy Twoje wydatki były mniejsze niż kwota przyznana w ramach grantu? Czy środki zostały wdrożone prawidłowo, czy część budżetu zawierała więcej, mniej lub niepotrzebne? Czy masz inne środki poza Google Season of Docs, których możesz użyć?
Dwóch członków grupy SIG GloriousPickle PickleDocs pracowało jako autorzy dokumentacji technicznej (jeden w Europie, a drugi w Argentynie). Dzięki nim mogliśmy oszacować zakres prac i znaleźć podobne budżety projektów, porównując pracę nad wersją roboczą oferty pakietowej, którą wykonali wcześniej. Mieliśmy też 1000 USD z nieograniczonego sponsoringu z naszego spotkania PicklePals w 2019 r., które przeznaczyliśmy na ten projekt.
Nieprzewidzianym wydatkiem było wypożyczenie hotspotu Wi-Fi dla naszego autora technicznego, ponieważ znajdował się on w obszarze dotkniętym pożarami i utracił dostęp do internetu w domu. Wysłaliśmy też mniej koszulek niż planowaliśmy, więc wszystko się wyrównało.
Dodatkowo zdecydowaliśmy się wynagrodzić współpracownikowi GloriousPickle, @Piccalily (który w przeszłości był zawodowym korektorem), aby pomógł w korekturze i weryfikacji dokumentacji przygotowanej przez copywritera.
Uczestnicy
Kto pracował nad tym projektem (użyj nazw użytkowników, jeśli proszą o to uczestnicy)? Jak znalazłeś/znalazłaś i zatrudniłeś/zatrudniłaś pisarza technicznego? Jak znalazłeś(-aś) innych wolontariuszy lub płatnych uczestników? Jakie pełniły role? Czy ktoś zrezygnował? Czego dowiedziałeś/-aś się o rekrutacji, komunikacji i zarządzaniu projektami?
Główny zespół pracujący nad tym projektem:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (pomoc dla administratorów, GPPSC)
- @BBChips, @GloriousPicklePat (eksperci w danej dziedzinie)
- Sam Scribe (pisarz techniczny)
Znaleźliśmy go na liście repozytorium GitHub Google Season of Docs. Uznaliśmy, że ich doświadczenie (Sam pracował w magazynie kulinarnym i tworzył dokumentację dla stron internetowych) dobrze pasuje do naszego projektu. Sam dołączył do co 2 tygodnie odbywających się spotkań grupy roboczej PickleDocs SIG i opowiedział nam o tym projekcie, podając kilka bardzo cennych sugestii, które uwzględniliśmy w propozycji. Skontaktowaliśmy się też z dwoma innymi autorami technicznymi, których znamy z sieci SIG, ale żaden z nich nie był dostępny w okresie trwania programu.
Ponieważ strefa czasowa Sama pokrywała się tylko o kilka godzin z większością członków grupy PickleDocuments SIG, na naszym forum dyskusyjnym z informacjami o selektorach, którzy przebywali w strefie czasowej Sama i znali proces dodawania składników, poinformowaliśmy ich o tym, jak wygląda proces dodawania składników. @BBChips zaoferował się, że odpowie na pytania Sama i pomoże mu znaleźć innych ekspertów, jeśli zajdzie taka potrzeba. @GloriousPicklePat zgłosił się też na ochotnika, aby pomóc Samowi zrozumieć podstawową architekturę narzędzia i potencjalne komunikaty o błędach z interfejsu API, a także zapewnił wsparcie w usługach GitHub i git.
Niestety w połowie programu @VinegarViv musiał zrezygnować z udziału w projekcie z powodów osobistych. Członek zespołu GPPSC @GherKen zajął się kwestiami administracyjnymi i pytaniami dotyczącymi płatności.
Po kilku nieukończonych pytaniach (GloriousPickle korzysta z bezpłatnej instancji Slacka i czasami dyskusja toczy się tak szybko, że z powodu limitu archiwum kroczącego przestajemy rozmawiać) dowiedzieliśmy się, że należy prowadzić listę aktywnych pytań w udostępnionym dokumencie (użyliśmy udostępnionego dokumentu Google). Przed każdym spotkaniem członkowie grupy roboczej PickleDocs sprawdzali listę i upewniali się, że odpowiedzi zostaną udzielone przed zakończeniem spotkania. Sam mógł bezpośrednio skontaktować się z @BBChips, aby zadać pilne pytania.
Bardzo satysfakcjonuje nas współpraca z Samem i Samem, a poza tym, że zaktualizowaliśmy dokumentację GloriousPickle, sama w sobie zapaliła się swoją pasją do selekcjonowania treści.
Oś czasu
Przedstaw krótki przegląd harmonogramu projektu (wskaż przewidywany termin zakończenia lub etapy pośrednie, jeśli projekt jest w toku).
Podczas oczekiwania na ogłoszenie organizacji uczestniczących w programie Google Season of Docs członkowie grupy roboczej PickleDocs SIG szukali wcześniejszych prac, które mogłyby być przydatne dla Sama. W ciągu miesiąca znaleźliśmy kilka uwag z wcześniejszych starań o zaktualizowanie uciążliwej dokumentacji. Przeanalizowaliśmy też fragmenty materiałów związanych z kontrolą dojrzałości dokumentacji w repozytorium Google Opendocs.
Gdy otrzymaliśmy dobrą wiadomość o wyborze nas do udziału w sezonie Dokumentów Google, Sam i zespół PickleDocuments SIG spotkały się i opracowały szczegółowy harmonogram:
| Etap | Wykonawca |
|---|---|
| Sprawdzanie audytu dokumentów | 7 maja |
| Przypadki użycia logu tarcia 3 | 14 maja |
| Sprawdzanie dzienników problemów z udziałem @GloriousPicklePat i @BBChips oraz udzielanie odpowiedzi na pytania | 28 maja |
| Pierwszy szkic zaktualizowanych dokumentów – przypadek użycia 1 | 25 czerwca |
| Przypadek użycia 1. Szkic sprawdzony przez @GloriousPicklePat i @KimChiCook | 2 lipca |
| Pierwszy szkic zaktualizowanych dokumentów – przypadek użycia 2 | 2 lipca |
| Wersja robocza przypadku użycia 2 sprawdzona przez @GloriousPicklePat i @Dillicious | 9 lipca |
| Pierwsza wersja robocza zaktualizowanych dokumentów przypadku użycia 3 | 9 lipca |
| Wersja robocza przypadku użycia 3 sprawdzona przez @Dillicious i @KimChiCook | 16 lipca |
| Odpowiedzi na wszystkie zapytania we wszystkich przypadkach użycia | 30 lipca |
| Większość członków grupy roboczej PickleDocs była na urlopie w dniach 1–20 sierpnia | -- |
| Rozpoczęcie testowania nowych dokumentów w społeczności (publikowanie dokumentów jako wersji roboczych na stronie GloriousPickle) | 21 sierpnia |
| Wdrożone opinie z testów | 10 września |
| korekta i korekta nowych dokumentów; | 17 września |
| Usunięto stan wersji roboczej dokumentów, dokumenty zostały oficjalnie udostępnione | 28 września |
| Proces aktualizacji utworzonej dokumentacji | 1 listopada |
| To studium przypadku zostało utworzone | 8 listopada |
| Studium przypadku zostało przesłane | 16 listopada |
W budżecie projektu zakładaliśmy, że copywriter techniczny będzie poświęcać na niego 10–15 godzin tygodniowo. Sam prowadził zapisy czasu spędzonego na nauce i średnio poświęcał na to 11,5 godziny tygodniowo.
Wyniki
Co zostało utworzone, zaktualizowane lub w inny sposób zmienione? W razie możliwości dodaj linki do opublikowanej dokumentacji. Czy w ofercie były jakieś elementy, które nie zostały utworzone? Wymień je również.
Opracowano 3 główne przypadki użycia z pełnymi instrukcjami dla użytkowników:
Jak dodać nowy składnik do GloriousPickle
Jak dodać wariant składnika do GloriousPickle
Jak zaktualizować lub poprawić składnik w GloriousPickle
W tych przewodnikach znalazły się też nowe szablony żądań pull, które ułatwiały publikowanie treści.
Podczas projektu Sam stworzył mały słowniczek z pojęciami, które udało mu się poznać. Został on opublikowany na stronie projektu GloriousPickle.
W wiki projektu dodaliśmy instrukcje aktualizowania tych przewodników.
Dołączyliśmy ściągawkę dla nowych użytkowników GitHuba, aby pomóc im korzystać z naszych procesów i narzędzi, ale gdy spojrzeliśmy na dostępne zasoby, udało nam się utworzyć ściągawkę dotyczącą innego projektu.
Dane
Jakie wskaźniki wybrałeś/wybrałaś do pomiaru skuteczności projektu? Czy udało Ci się zebrać te dane? Czy dane ściśle korelowały z oczekiwanymi wynikami projektu? Czy dane zmieniły się od czasu przesłania propozycji?
W naszej propozycji zaproponowaliśmy 2 rodzaje danych:
- liczba żądań pull związanych ze składnikami;
- liczba próśb o przechwycenie od nowych współtwórców
We wrześniu (pierwszym pełnym miesiącu od opublikowania wersji roboczej dokumentacji) odnotowaliśmy wzrost liczby żądań pull związanych ze składnikami o 5% (z 20 w sierpniu do 21 we wrześniu). W tym czasie 3 nowych współtwórców przesłało łącznie 4 żądania pull (w porównaniu z 2 nowymi współtwórcami, którzy przesłali 2 żądania pull w sierpniu). Planujemy śledzić te wskaźniki co miesiąc.
Od 1 stycznia będziemy też co kwartał śledzić liczbę współtwórców, którzy wnieśli łącznie więcej niż 3 wkłady, począwszy od publikacji dokumentacji.
Z naszych obserwacji wynika, że nowa dokumentacja ułatwia nowym współtwórcom dodawanie składników do bazy danych GloriousPickle. Jeden z nich napisał w komentarzu do swojego PR, że próbował to zrobić wcześniej, ale nie udało mu się to, ponieważ nie rozumiał procesu.
Analiza
Co poszło dobrze? Co było nieoczekiwane? Z jakimi przeszkodami lub niepowodzeniami się spotkałeś/się spotkałaś? Czy uważasz, że Twój projekt był udany? Dlaczego? (Jeśli jest za wcześnie, aby to stwierdzić, wyjaśnij, kiedy planujesz ocenić skuteczność projektu).
Jesteśmy bardzo zadowoleni z wyników projektu Google Season of Docs i uważamy go za udany. Nowa dokumentacja jest przejrzysta i przydatna. Zauważyliśmy już pewien wzrost liczby pull requestów związanych ze składnikami oraz liczby pull requestów od nowych współtwórców.
Cieszył nas też fakt, że w procesie uczestniczyła prawie cała społeczność GloriousPickle, która przekazała nam opinie na temat pierwotnej propozycji i przetestowała nowe dokumenty w postaci wersji roboczej.
Pojawiło się kilka nieoczekiwanych przeszkód, ale szczęśliwie pożary w stanie Sam nie spowodowały większych szkód niż przerwa w działaniu internetu. Przykro nam, że @VinegarViv opuściła projekt. Życzymy jej i jej rodzinie wszystkiego najlepszego i mamy nadzieję, że wkrótce znowu się spotkamy.
Zanim Sam zaczął pracować nad dokumentacją, nie zdawał sobie sprawy, że wiele terminów i akronimów związanych z ogóreczami będzie niezrozumiałych dla osób, które nie mają żadnego doświadczenia w przyrządzaniu ogórków. Jednak Sam stworzył listę wszystkich nieznanych terminów i definiował je we własnych badaniach oraz prosząc członków społeczności o wyjaśnienia i informacje referencyjne. Ten słowniczek będzie bardzo pomocny w przyszłości, gdy będziesz zapraszać do społeczności więcej osób.
Podsumowanie
W 2–4 akapitach podsumuj swoje doświadczenia z projektu. Podkreśl, czego się nauczyłeś, i wskaż, co według Ciebie należałoby robić inaczej w przyszłości. Jaką radę dałbyś/dałabyś innym projektom, które próbują rozwiązać podobny problem z dokumentacją?
Jednym słowem, to była świetna zabawa! Zrealizowaliśmy materiały, które otrzymaliśmy, i wygląda na to, że nasze dane są zgodne z naszymi celami.
Ogromną rolę w sukcesie tego projektu odegrała nasza współpraca z Sam Scribe, autorką treści technicznych. [I did not write this—Sam] Chociaż Sam nie miał żadnego doświadczenia z pickle ani GitHubem, jako doświadczony autor tekstów technicznych bez problemu zagłębił się w nowy temat, zadawał pytania i przeprowadzał badania. Sam szybko zdobył narzędzia do projektów (używamy tablicy kanban do śledzenia pracy), ale też nasze żarty. Cieszymy się, że Sam wpadł na pomysł marynowania i że udało nam się go wdrożyć w naszej społeczności.
W innych projektach zalecamy:
- Proponowane zmiany powinny być niewielkie i łatwe do wprowadzenia. (Początkowo chcieliśmy dołączyć do naszej propozycji dokumentację dotyczącą korzystania z szacowania w przypadku przemysłowych maszyn do marynowania w partiach, ale zrezygnowaliśmy z tego, ponieważ jedna z naszych użytkowniczek, która jest bardzo zaangażowana w projektowanie maszyn do marynowania w ramach projektu open source, miała pisać pracę doktorską w ramach programu). Ostatecznie okazało się, że Sam ma mnóstwo pracy.
- Wykorzystuj swoje sieci, gdy szukasz osoby odpowiedzialnej za kwestie techniczne. Zapytaj społeczność o polecenia. Znaleźliśmy Sama na GitHubie w ramach Google Season of Docs, ale mieliśmy pewność, że współpraca z nim będzie udana, ponieważ rozmawialiśmy z kilkoma osobami w trakcie rekrutacji.
- Witamy w społeczności autora treści technicznych. Sam powiedział nam, że entuzjastyczne nastawienie zespołu GloriousPicklers ułatwiło mu zadawanie pytań.
- Pomóż autorowi tekstów technicznych w nabyciu umiejętności związanych z open source. Sam nigdy wcześniej nie korzystał z git, ale po obejrzeniu kilku samouczków szybko się tego nauczył. Początkowo Sam martwił się o liczbę opinii społeczności i sposób jego wykorzystania, ale model „zgodności” w naszej społeczności („konsensus jest osiągany, gdy rozwiązujemy wszystkie problemy, ale niekoniecznie uwzględniany”), pozwolił mu pewnie odpowiadać na krytykę dzięki swojemu doświadczeniu związanemu z pisaniem technicznym.
Dodatek
Jeśli masz inne materiały, do których chcesz dodać link (np. jeśli masz utworzony kontrakt na współpracę z Twoim autorem technicznym, którym chcesz się podzielić, lub szablony projektu dokumentacji albo inne otwarte zasoby dokumentacji, możesz je tutaj wymienić i dodać do nich linki). W załączniku możesz też podać linki do narzędzi lub zasobów dokumentacji, których użyłeś/użyłaś, oraz podziękowania lub podziękowania, które nie pasują do sekcji powyżej.
Poświadczenia
Nasz zespół chciałby podziękować następującym osobom i podkreślić:
- @Dillicious dziękuje swojemu partnerowi i low-fi hip hop radio
- @KimChiCook dziękuje swojej 할머니 za to, że nauczyła go robić pikle
- @Piccalily dziękuje Chicago Manual of Style Online
- @GherKen dziękuje swoim 3 dzieciom za zjedzenie wszystkich ogórków, które udało mu się zrobić
- @VinegarViv dziękuje reszcie zespołu za zrozumienie, że zrezygnowała z pełnienia tej funkcji
- @BBChips dziękuje za najlepsze dostępne produkty, które nie są ogórkami, czyli wafelki Tunnock's Caramel Wafers
- @GloriousPicklePat pragnie podziękować organizacji PickleDocuments (SIG) za podjęcie tego projektu
- Sam Scribe dziękuje całej społeczności GloriousPickle, a szczególnie użytkownikom Picklers, którzy wysłali słoiki podczas ich niedoboru latem 2021 r., dzięki czemu mogli oni rozpocząć proces przygotowywania pysznych ogórków.