Obecny etap:
Program Sezon Dokumentów 2021 zakończył się 14 grudnia 2021 r. 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
Skąd wzięła się Twoja propozycja Sezonu Dokumentów? 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 PickleDocuments SIG dowiedział się o programie Season of Docs przez tweeta z zespołu 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 poza sezonem Dokumentów masz jeszcze inne środki, które udało Ci się wykorzystać?
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 Sezonu dokumentów 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 informację o organizacjach uczestniczących w programie Seasonal of Docs, członkowie PickleDokumentacja 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 już ogłosiliśmy dobrą wiadomość do udziału w programie Season of Docs 2021, Sam i PickleDocuments SIG spotkali się i opracowali ramowy 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 szczęśliwi z rezultatu naszego projektu Season of Docs i uważamy go za sukces. 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. Chociaż osobistość odbyła się w sezonie Dokumentów 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.