Bieżący etap:
Program Sezon na dokumenty 2021 zakończył się 14 grudnia 2021 r. 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 lub 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 narzędzia GloriousPickle jest czasochłonne i skomplikowane, a narzędzie nie jest dobrze udokumentowane. 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 oferty pakietowej
Jak powstała Twoja propozycja dotycząca Sezonu dokumentów? Jaki proces zastosowała Twoja organizacja, aby podjąć decyzję dotyczącą pomysłu? Jak zbierasz i uwzględniasz opinie?
Grupa SIG GloriousPickle PickleDocs dowiedziała się o programie Sezon na Dokumenty z tweeta Open Source Programs Office w Google. 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 zaoferowała swoją pomoc w ramach programu.
Po omówieniu i uwzględnieniu otrzymanych opinii propozycja została przesłana do komitetu kierującego projektem GloriousPickle w celu przeprowadzenia 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 pojawiły się jakieś nieoczekiwane wydatki? Czy wydałeś/wydałaś mniej niż przyznana kwota grantu? Czy masz inne środki poza 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). Pomagali nam oszacować zakres prac i znaleźć podobne budżety projektów, porównując wcześniej przygotowane przez siebie projekty. 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 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 zaoferował też pomoc w zrozumieniu podstawowej architektury narzędzia i możliwych komunikatów o błędach z interfejsu API. Podał też informacje o GitHub i git.
Niestety w połowie programu @VinegarViv musiał zrezygnować z projektu z przyczyn osobistych. Członkowie GPPSC, @GherKen, zajął się pytaniami dotyczącymi kwestii administracyjnych i płatności.
Po tym, jak przegapiliśmy kilka pytań (GloriousPickle używa bezpłatnej wersji Slack, a czasami rozmowa rozwija się tak szybko, że tracimy rozmowy z powodu limitu archiwizacji) dowiedzieliśmy się, że powinniśmy prowadzić listę bieżących 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 przyjemnie było nam współpracować z Sam. Oprócz zaktualizowania dokumentacji GloriousPickle Sam stał się też zapalonym konserwantem.
Oś czasu
Przedstaw krótki przegląd harmonogramu projektu (wskaż przewidywany termin zakończenia lub etapy pośrednie, jeśli projekt jest w toku).
W oczekiwaniu na ogłoszenie organizacji uczestniczących w programie 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 notatki z wcześniejszych prób zaktualizowania dokumentacji, które zostały wstrzymane, a także przeanalizowaliśmy części materiałów z audytu dojrzałości dokumentacji w repozytorium opendocs Google.
Gdy otrzymaliśmy dobrą wiadomość, że zostaliśmy wybrani do udziału w sezonie Dokumentów 2021, Sam i grupa robocza PickleDocs SIG ustalili wstępny harmonogram:
| Etap | Wykonawca |
|---|---|
| Sprawdzanie audytu dokumentów | 7 maja |
| 3 przypadki użycia rejestru zgłaszania błędów | 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 |
| Przypadek użycia 2. Szkic sprawdzony przez @GloriousPicklePat i @Dillicious | 9 lipca |
| Pierwszy szkic zaktualizowanych dokumentów (przypadek użycia 3) | 9 lipca |
| Przypadek użycia 3. Wersja robocza sprawdzona przez @Dillicious i @KimChiCook | 16 lipca |
| Odpowiedziano 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 |
| Dołączono opinię z testu | 10 września |
| korekta i korekta nowych dokumentów; | 17 września |
| Usunięto stan „Wersja robocza”, dokumenty zostały oficjalnie opublikowane | 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
Te przewodniki zawierały też nowe szablony próśb o przechwycenie, które ułatwiają tworzenie wkładów.
Ponadto w trakcie projektu Sam stworzył niewielki glosariusz z nauką pojęć, który opublikowano również w witrynie projektu GloriousPickle.
W wiki projektu dodaliśmy instrukcje aktualizowania tych przewodników.
Chcieliśmy utworzyć kartę podpowiedzi dla osób, które dopiero zaczynają korzystać z GitHuba, aby ułatwić im korzystanie z naszych procesów i narzędzi. Po przejrzeniu dostępnych zasobów zdecydowaliśmy się jednak użyć karty podpowiedzi z 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 były powiązane z oczekiwanymi wynikami projektu? Czy dane zmieniły się od czasu przesłania propozycji?
W naszej propozycji uwzględniliś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 (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) i zaobserwowaliśmy 3 nowych użytkowników, którzy przesłali łącznie 4 żądania (w porównaniu z 2 nowymi współtwórcami, którzy w sierpniu złożyli 2 żądania pull). Planujemy śledzić te dane co miesiąc.
Od 1 stycznia będziemy także śledzić liczbę współtwórców, którzy przesłali łącznie więcej niż 3 materiały, zaczynając co kwartał po opublikowaniu 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 swój projekt za 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 „Sezon na dokumenty” 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. Sam jednak postanowił stworzyć listę wszystkich nieznanych mu terminów i zdefiniować je na podstawie własnych badań oraz próśb o wyjaśnienia i odniesienia do członków społeczności. 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. Czy masz jakieś wskazówki dla innych projektów, które miałyby pomóc w rozwiązaniu podobnego problemu z użyciem dokumentacji?
Jednym słowem, to była świetna zabawa! Udało nam się zrealizować wszystkie wymagania dotyczące dokumentacji, a dane wydają się być zgodne z naszymi celami.
Ogromną rolę w sukcesie tego projektu odegrała nasza współpraca z Sam Scribe, autorką treści technicznych. [Nie piszę tego – Sam] Chociaż Sam nie miał doświadczenia w pikielaniu ani pracy z GitHubem, jako doświadczony autor techniczny mógł z przyjemnością zagłębiać się w nową tematykę, zadawać pytania i szukać informacji. Sam szybko opanował nie tylko nasze narzędzia do zarządzania projektami (do śledzenia pracy używamy tablicy kanban), ale też nasze żarty o ogórach. Bardzo się cieszymy, że Jan złapał robaka i zamieszczał go w naszej społeczności.
Zalecamy, aby inne projekty:
- 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.
- Szukaj copywritera technicznego wśród swoich znajomych. Poproś wszystkich członków społeczności o rekomendacje. Chociaż spotkaliśmy Sama przez cały sezon Dokumentów na GitHubie, czuliśmy się pewnie, byśmy mogli z nim współpracować, bo w czasie, gdy rozmawialiśmy z kilkoma osobami.
- 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 obawiał się, ile informacji zwrotnych może otrzymać od społeczności i jak je wykorzystać, ale model „osiągnięcia ogólnego konsensusu” w naszej społeczności („konsensus jest osiągany, gdy wszystkie problemy zostaną rozwiązane, ale niekoniecznie w pełni”) pozwolił mu pewnie odpowiadać na krytykę, wykorzystując swoją wiedzę techniczną.
Dodatek
Jeśli chcesz podać link do innych materiałów (na przykład jeśli masz podpisaną umowę na współpracę z twórcą treści technicznych, którą chcesz udostępnić, albo szablony projektu z dokumentacją lub innymi otwartą dokumentacją, możesz je tutaj wymienić i połączyć). 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 pragnie podziękować „Chicago Manual of Style Online” w Chicago
- @GherKen chce podziękować swoim trojkom dzieci za zjedzenie wszystkich przygotowanych przez niego korniszonów
- @VinegarViv chce podziękować pozostałym członkom zespołu za pomoc w odejściu z pracy
- @BBChips chce podziękować za najlepsze wafle karmelowe od Tunnocka
- @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.