Obecny etap:
Ogłoszenie wyników. Zobacz oś czasu.
Użyj tego przykładu, aby utworzyć własny raport ze studium przypadku.
PicklePlus: dokumentowanie narzędzia do przekazywania darowizn
Organizacja lub projekt: Glorious Pickle Link do głównej witryny organizacji lub projektu
Opis organizacji: GloriousPickle (wersja 1.2.3, pierwsza wersja w 2009 r.) to biblioteka na licencji MIT, która umożliwia łatwe obliczanie idealnego stosunku soli, cukru, octu i przypraw w przypadku wszystkich możliwych dopraw warzyw, od pojedynczej rzodkiewki do rzodkiew w kontenerach.
Autorzy: opcjonalnie: lista autorów studium przypadku; w razie potrzeby użyj nazw użytkowników
Omówienie problemu/streszczenie propozycji
Jaki problem próbowałeś(-aś) rozwiązać przy użyciu nowej lub ulepszonej dokumentacji? Jeśli to możliwe, dodaj link do strony oferty pakietowej w witrynie projektu.
Dodawanie składników do bazy danych składników narzędzia GloriousPickle jest czasochłonne i skomplikowane, a do tego narzędzia nie ma odpowiedniej dokumentacji. Wielu z nich nie ma doświadczenia w korzystaniu z git ani w wysyłaniu żądań pull. Oznacza to, że w danych o składnikach GloriousPickle występują poważne luki w danych, przez co nasze narzędzie jest mniej przydatne. Mamy nadzieję, że ulepszając dokumentację dotyczącą dodawania nowych składników, zachęcimy nowych współtwórców i zachęcimy ich do picia.
Opis projektu
Tworzenie propozycji
Jak powstała propozycja Sezonu Dokumentów Google? W jaki sposób Twoja organizacja podjęła decyzję o dążeniu do celu? W jaki sposób udało Ci się zebrać opinie i uwzględnić w nich opinie?
Zespół GloriousPickle PickleDokumentacja SIG dowiedział się o programie Google Season of Docs przez tweeta z biura programów Google Open Source Programs Office. Zespół SIG omówił program podczas spotkania, które odbywa się co 2 tygodnie, oraz zgodził się opracować ofertę. Dwóch członków SIG (@KimChiCook i @Dillicious) zgłosiło się na ochotnika do pracy nad wersją roboczą oferty, którą ma ona sprawdzić podczas następnego spotkania.
Gdy zespół PickleDokumentacja SIG zaakceptował wersję roboczą oferty, do szerszego projektu wysłano e-maila z prośbą o opinię. Opinie 14 członków społeczności podzieliło się z nami swoimi opiniami. Jednym z nich był @GloriousPicklePat, który zarządza interfejsem API do dodawania składników. @GloriousPicklePat zgłosił się do pomocy podczas programu.
Po zapoznaniu się z otrzymanymi opiniami propozycja została przesłana do komitetu sterującego projektu GloriousPickle w celu głosowania. Wszyscy 5 członków GPPSC zagłosowało +1 na przesłanie propozycji i zgłoszenia, a @VinegarViv zgodziła się pomóc w utworzeniu konta Open Collective, które jest wymagane do udziału w programie i nadzorowania płatności.
Budżet
Zamieść krótką sekcję dotyczącą budżetu. Jak oceniasz pracę? Czy wystąpiły jakieś nieoczekiwane wydatki? Czy ostatecznie udało Ci się wydać mniej niż kwota otrzymana w ramach grantu? Czy środki zostały przydzielone prawidłowo, czy też niektóre pozycje w budżecie były bardziej/mniej lub niepotrzebne? Czy masz inne środki, które udało Ci się wykorzystać poza sezonem Dokumentów Google?
Dwóch członków zespołu GloriousPickle PickleDokumentacja SIG pracowało jako pisarze techniczni (jedną w Europie i jedną w Argentynie). Zespół pomógł nam oszacować ilość pracy i znaleźć podobne budżety projektów, porównując wcześniejsze wersje roboczej oferty pakietowej. Pozostało też 1000 USD w nieograniczonym zakresie środków na sponsorowanie z konferencji PicklePals z 2019 roku, które przydzieliliśmy do projektu.
W okolicy dotkniętych pożarami i utratą dostępu do internetu nasz pisarz techniczny mógł wynająć hotspot Wi-Fi w obszarze dotkniętym pożarami. Poza tym rozesłaliśmy do uczestników mniej koszulek niż planowaliśmy, więc udało nam się wypracować równowagę.
Postanowiliśmy też wynagrodzić współtwórczyni kanału GloriousPickle, @Piccalily (która w czasach swojej małoletniej pracy redaktorskiej), za pomoc w pisaniu i sprawdzaniu dokumentów.
uczestników
Kto pracował nad tym projektem (użyj nazw użytkowników, jeśli o to poprosili)? Jak udało Ci się znaleźć i zatrudnić twórcę technicznego? Jak udało Ci się znaleźć innych wolontariuszy lub płacących uczestników? Jakie pełniły te role? Czy ktoś opuścił rozmowę? Czego dowiedziałeś się o rekrutacji, komunikacji i zarządzaniu projektami?
Główny zespół pracujący nad tym projektem to:
- @Dillicious, @KimChiCook (PickleDocuments SIG)
- @Piccalily (edytor tekstu)
- @GherKen, @VinegarViv (pomoc dla administratorów, GPPSC)
- @BBChips, @GloriousPicklePat (eksperty ds. konkretnych tematów)
- Sam Scribe (autor techniczny)
Znaleźliśmy Sam Scribe w repozytorium Google Season of Docs na GitHubie. Uznaliśmy, że ich doświadczenia (praca dla magazynu kulinarnego oraz pisanie dokumentacji do stron internetowych) pasują do naszego projektu. Sam Sam uczestniczył w rozmowie z grupą PickleDocuments SIG co 2 tygodnie i omawiał z nami cały projekt, przedstawiając kilka bardzo cennych sugestii, które włączyliśmy do oferty. Skontaktowaliśmy się również z dwoma innymi twórcami treści technicznych znanymi nam w sieciach członków SIG, ale żaden z nich nie był dostępny w czasie trwania programu.
Strefa czasowa Jana pokrywała się tylko przez kilka godzin z większością członków PickleDokumentacja SIG, dlatego zaprosiliśmy na forum do dyskusji osób, które znajdują się w strefie czasowej Sama i znają proces dodawania składników. @BBChips odpowiada na pytania Sama i pomaga w razie potrzeby znaleźć innych ekspertów. Twórca @GloriousPicklePat również zgłosił się do pomocy Samowi w zrozumieniu jego architektury i możliwych komunikatów o błędach z interfejsu API. Udzielił też pomocy GitHubowi i git.
Niestety w trakcie programu @VinegarViv musiał(a) wycofać się z projektu z powodów osobistych. @GherKen, członek GPPSC, zajął się kwestiami administracyjnymi i płatnościami.
Pomimo kilku brakujących pytań (GloriousPickle używa bezpłatnej instancji Slacka i czasami dyskusja rozwija się tak szybko, że tracimy rozmowy z powodu ruchomego limitu archiwów) doszliśmy do wniosku, że warto zachować listę aktywnych pytań w udostępnionym dokumencie (użyliśmy udostępnionego dokumentu Google). Członkowie PickleDokumentacja SIG sprawdzali ją przed każdym spotkaniem i uzyskali odpowiedzi przed końcem spotkania. Sam mógł skontaktować się bezpośrednio z @BBChips, aby zadać pilne pytania.
Współpraca z Samem i Samem sprawiła, że nie tylko zaktualizowaliśmy dokumentację GloriousPickle, ale też sami bardzo zaangażowaliśmy się w selektora.
Oś czasu
Przedstaw w skrócie harmonogram projektu (podaj szacowaną datę zakończenia lub etapy pośrednie, jeśli projekt jest trwający).
Podczas gdy czekaliśmy na ogłoszenie uczestników programu Sezon Dokumentów Google, członkowie grupy PickleDocuments SIG szukali wszystkich poprzednich prac, które naszym zdaniem byłyby dla niego przydatne. W ciągu miesiąca znaleźliśmy kilka informacji z wcześniejszych prac związanych z aktualizacją dokumentacji, która się opóźniła. Przeanalizowaliśmy też części materiałów do kontroli dojrzałości dokumentacji w repozytorium Google opendocs.
Gdy tylko usłyszeliśmy, że zostaliśmy wybrani do udziału w programie Sezon Dokumentów Google, Sam i PickleDocuments SIG spotkali się i ustalili rygorystyczny harmonogram:
| Etap | Zrealizowany przez |
|---|---|
| Sprawdź kontrolę dokumentów | 7 maja |
| Dziennik tarcia 3 – przypadki użycia | 14 maja |
| Przeglądaj dzienniki błędów, odpowiadaj na pytania @GloriousPicklePat i @BBChips | 28 maja |
| Pierwsza wersja robocza zaktualizowanych dokumentów – przypadek użycia 1 | 25 czerwca |
| Przypadek użycia 1 wersja robocza sprawdzona przez @GloriousPicklePat i @KimChiCook | 2 lipca |
| Pierwsza wersja robocza zaktualizowanych dokumentów – przypadek użycia 2 | 2 lipca |
| Przykład zastosowania nr 2 w wersji roboczej sprawdzonej przez @GloriousPicklePat i @Dillicious | 9 lipca |
| Pierwsza wersja robocza zaktualizowanych dokumentów – przypadek użycia 3 | 9 lipca |
| Przykład zastosowania 3 w wersji roboczej sprawdzonej przez @Dillicious i @KimChiCook | 16 lipca |
| Wszystkie zapytania, na które udzielono odpowiedzi we wszystkich przypadkach użycia | 30 lipca |
| Większość pracowników PickleDokumentacja SIG była na wakacjach 1–20 sierpnia | -- |
| Rozpocznij testowanie nowych dokumentów w społeczności (dokumenty opublikowane jako wersje robocze w witrynie GloriousPickle) | 21 sierpnia |
| Uwzględniono opinię z testu | 10 września |
| Kopiuj i sprawdzaj nowe dokumenty | 17 września |
| Wersja robocza stanu dokumentów została usunięta, dokumenty zostały oficjalnie udostępnione | 28 września |
| Proces aktualizowania utworzonej dokumentacji | 1 listopada |
| To studium przypadku zostało utworzone | 8 listopada |
| Przesłano studium przypadku | 16 listopada |
W budżecie oferty pakietowej szacowaliśmy, że specjalista ds. technicznych będzie musiał poświęcić 10–15 godzin tygodniowo na pracę nad projektem. Jan prowadził zapisy dotyczące czasu poświęconego na korzystanie z aplikacji i wynosił średnio 11,5 godziny tygodniowo.
Wyniki
Co zostało utworzone, zaktualizowane lub w inny sposób zmienione? Jeśli są dostępne, podaj linki do opublikowanej dokumentacji. Czy w ofercie pakietowej znajdują się elementy, które nie zostały utworzone? Warto je również wymienić.
W ramach pełnych instrukcji dla użytkowników omówiono 3 główne przypadki użycia:
Jak dodać nowy składnik do chleba GloriousPickle
Jak dodać wariant składnika do produktu GloriousPickle
Jak zaktualizować lub poprawić składnik w GloriousPickle
Przewodniki te zawierały też nowe szablony żądań pull, które ułatwiają przekazywanie treści.
Dodatkowo w trakcie projektu Sam stworzył mały słowniczek pojęć nauczonych w Pickle, który został również opublikowany na stronie projektu GloriousPickle.
Dodaliśmy instrukcje aktualizowania tych instrukcji dla użytkowników do naszej witryny wiki o projektach.
Zdecydowaliśmy się przygotować ściągawkę dla nowych użytkowników GitHuba, aby pomóc im w korzystaniu z naszych procesów i narzędzi. Jednak po przejrzeniu dostępnych zasobów udało nam się utworzyć ściągawkę z innego projektu.
Wskaźniki
Jakie dane wybrałeś do pomiaru powodzenia projektu? Czy udało Ci się zebrać te dane? Czy wskaźniki były odpowiednio skorelowane z rezultatami projektu, na których Ci zależy? Czy od czasu przesłania oferty pakietowej zmieniły się Twoje dane?
W naszej propozycji zaproponowaliśmy 2 rodzaje danych:
- liczba żądań pull dotyczących składników
- liczba żądań pull od nowych współtwórców
We wrześniu (pierwszy pełny miesiąc od opublikowania wersji roboczej dokumentacji) zaobserwowaliśmy 5-procentowy wzrost liczby żądań pull dotyczących składników (z 20 sierpnia do 21 września) oraz 3 nowych współtwórców, którzy przesłali łącznie 4 żądania (w porównaniu z 2 nowymi współtwórcami, którzy przesłali 2 żądania pull w sierpniu). Planujemy co miesiąc śledzić te dane.
Od 1 stycznia będziemy także śledzić liczbę współtwórców, którzy wprowadzili łącznie więcej niż 3 treści, zaczynając co kwartał po opublikowaniu dokumentacji.
Wydaje nam się, że dzięki tej nowej dokumentacji nowi współtwórcy mogą dodawać składniki do bazy danych składników GloriousPickle. Jeden z nowych współtwórców wspomniany w komentarzu dotyczącym PR, który już spróbował, ale nie ukończył procesu, ponieważ nie rozumie, na czym polega proces.
Analiza
Co poszło dobrze? Co było nieoczekiwane? Z jakimi przeszkodami lub przeciwnościami się spotkałeś(-aś)? Czy uważasz swój projekt za udany? Dlaczego? Jeśli jest jeszcze za wcześnie, aby podać szczegóły, wyjaśnij, kiedy będziesz w stanie ocenić sukces projektu.
Jesteśmy bardzo zadowoleni z wyników projektu Sezon Dokumentów Google i uznajemy go za udany. Nowa dokumentacja jest jasna i pomocna. Odnotowaliśmy już wzrost liczby żądań pull dotyczących składników oraz liczby takich żądań od nowych współtwórców.
Cieszymy się również, że w spotkaniu wzięła udział prawie cała społeczność GloriousPickle – wysłuchaliśmy opinii na temat pierwotnej propozycji i przetestowaliśmy nowe dokumenty w wersji roboczej.
Natknęliśmy się na kilka nieoczekiwanych przeszkód — byliśmy wdzięczni, że pożary lasów w stanie Sama nie przyniosły większych szkód niż brak połączenia z internetem. Szkoda nam też, że straciliśmy @VinegarViv w projekcie. Życzymy jej i jej rodzinie wszystkiego dobrego i mamy nadzieję, że wkrótce się zobaczymy.
Zanim Sam przystąpił do pracy nad dokumentacją, nie zdawaliśmy sobie sprawy, że bez trudu nie zdaliśmy sobie sprawy z liczby terminów i akronimów związanych z ogórkami. Jednak Sam przygotował listę wszystkich nieznanych terminów i zdefiniował je, prowadząc do nich własne badania oraz prosząc członków społeczności o wyjaśnienia i źródła wiedzy. Słowniczek ten jest niezwykle pomocny w pozyskaniu większej liczby osób zainteresowanych tego rodzaju wyrobami w przyszłości.
Podsumowanie
W 2–4 akapitach podsumuj swoje wrażenia związane z projektem. Podkreśl to, czego się nauczyłeś/aś i co Twoim zdaniem warto byłoby robić w przyszłości. Jakich rad możesz udzielić innym projektom, które próbują rozwiązać podobny problem, korzystając z dokumentacji?
Krótko mówiąc, nasze wrażenia były ciężkie! Udało nam się zrealizować wszystkie cele w zakresie dokumentacji, a nasze wskaźniki są zgodne z naszymi celami.
W dużej mierze okazała się szczęścia, że współpracowaliśmy z autorem tekstów technicznych, Samem Scribe. [Nie ja to napisałem—Sam] Chociaż Sam nie miał doświadczenia w pikluniu ani doświadczeniu w usłudze GitHub, jako doświadczony pisarz techniczny potrafił poruszać się w nowym temacie, zadawać pytania i przeprowadzać badania naukowe. Sam szybko podjął nie tylko nasze narzędzia projektowe (używamy tablicy kanban do śledzenia pracy), ale też nasze żartobliwe żarty. Cieszymy się, że Jan wyłapał owada i wypchniliśmy go w naszej społeczności.
Innym projektom polecamy:
- Oferty powinny być krótkie i łatwe do zarządzania. (Chcieliśmy dołączyć do naszego zapytania dokumentację dotyczącą korzystania z naszego narzędzia do szacowania wyrobu wsadowego przemysłu. Pominęliśmy ją jednak, ponieważ w czasie trwania programu jeden z członków naszej społeczności był mocno zaangażowany w zajęcia open source maszyn do wypiekania ogórków. Mieliśmy już wystarczająco dużo pracy, żeby Sam się zajął!
- Szukaj autora tekstów technicznych, wykorzystując swoją sieć kontaktów. Poproś wszystkich członków społeczności o rekomendacje. Choć Sam należeliśmy do Sama podczas sezonu Dokumentów Google na GitHubie, czuliśmy się pewnie we współpracy z nimi, bo w okresie przesyłania zgłoszeń rozmawialiśmy z kilkoma osobami.
- Powitaj w społeczności swojego redaktora technicznego. Samuel poinformował nas, że entuzjastyczne podejście zespołu GloriousPicklers ułatwiło zadawanie pytań.
- Pomóż autorowi technicznemu zdobyć umiejętności open source. Sam nigdy wcześniej nie korzystał z git, ale po zapoznaniu się z kilkoma samouczkami szybko nabrał git. Początkowo Sam obawiał się, ile opinii otrzymają członkowie społeczności i jak je włączyć do niej. Jednak model oparty na „jednoznacznym konsensusie” naszej społeczności („konsensus został osiągnięty, gdy wszystkie problemy zostały rozwiązane, a niekoniecznie obecny) sprawił, że dzięki swojej wiedzy technicznej udowodnił, że odpowiada na krytykę.
Dodatek
Jeśli masz inne materiały, do których chcesz dodać link (np. masz umowę o współpracy z autorem dokumentacji, którą chcesz udostępnić, szablony projektu dokumentacji lub inne otwarte zasoby dokumentacji, możesz dodać je tutaj i podać link). Załącznik to także dobre miejsce na podanie linków do używanych przez Ciebie narzędzi i zasobów do dokumentacji. Możesz też dodać podziękowanie i podziękowania, które mogą nie mieścić się w powyższych sekcjach.
Poświadczenia
Nasz zespół wyróżnia następujące osoby i rzeczy:
- @Dillicious chce podziękować swojemu partnerowi i zagrać w niskim hip-hopie w radiu
- @KimChiCook chciałby podziękować 할머니 za nauczenie go, jak piszczeć pikle
- @Piccalily chce podziękować Chicago Manual of Style Online
- @GherKen chciałby podziękować trójce swoich dzieci za zjedzenie wszystkich przyrządzanych pikli
- @VinegarViv chce podziękować pozostałym członkom zespołu za umożliwienie jej rezygnacji
- @BBChips chce podziękować za najlepsze dostępne dania, które nie są pikantne, czyli wafle karmelowe Tunnock.
- @GloriousPicklePat chce podziękować zespołowi PickleDokumentacja SIG za skorzystanie z tego projektu
- Sam Scribe pragnie podziękować całej społeczności GloriousPickle, a zwłaszcza tym osobom, które z powodu niedoboru słoików w lecie 2021 r. wysyłały im słoiki, zaczynając od pysznych ogórków.