Obecny etap:
opracowywanie dokumentacji. Sprawdź oś czasu.
Ten przykład pomoże Ci utworzyć własny raport ze studium przypadku.
PicklePlus: dokumentowanie narzędzia do przekazywania darowizn GloriousPickle
Organizacja lub projekt: Glorious Pickle Link do głównej witryny organizacji lub projektu
Opis organizacji: GloriousPickle (obecna wersja 1.2.3, pierwsza wersja w 2009 r.) to biblioteka na licencji MIT umożliwiająca łatwe obliczanie idealnego stosunku soli, cukru, octu i przypraw w przypadku każdego możliwego do marynowania warzywa – od pojedynczych ogórków po ciężary rzodkiew.
Autorzy: opcjonalnie: wyświetl listę autorów studium przypadku; w razie potrzeby użyj nazw użytkowników
Opis problemu/Streszczenie propozycji
Jaki problem próbowałeś(-aś) rozwiązać przy użyciu nowej lub ulepszonej dokumentacji? W miarę możliwości podaj 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 narzędzie nie ma dobrej dokumentacji. Wielu z nich nie ma doświadczenia w korzystaniu z git ani w wysyłaniu żądań pull. W rezultacie narzędzie GloriousPickle ma poważne luki w danych dotyczących składników, co z kolei sprawia, że jest ono 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 oferty pakietowej
Skąd wzięła się Twoja propozycja Sezonu Dokumentów Google? W jaki sposób Twoja organizacja podjęła decyzję o danym pomysłie? W jaki sposób zbierałeś(-aś) opinie i uwzględniasz w nich opinie?
Zespół GloriousPickle PickleDoc SIG dowiedział się o programie Sezon Dokumentów Google z tweeta od Google Open Source Programs Office. Zespół SIG omówił program na spotkaniu odbywającym się co 2 tygodnie i zgodził się opracować ofertę. Dwie osoby z SIG (@KimChiCook i @Dillicious) zgłosiły się do współpracy nad wersją roboczą oferty do sprawdzenia na następnym spotkaniu.
Gdy zespół PickleDoc 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 dotyczyły na przykład użytkownika @GloriousPicklePat, który zarządza interfejsem API do dodawania składników. @GloriousPicklePat zgłosił się do pomocy jako materiał podczas realizacji programu.
Po przeanalizowaniu i uwzględnieniu otrzymanych opinii 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 za przesłanie propozycji i zgłoszenia, a @VinegarViv zgodziło się pomóc w utworzeniu konta Open Collective wymaganego do uczestnictwa w programie i nadzorowania płatności.
Budżet
Uwzględnij krótką sekcję dotyczącą budżetu. Jak oceniasz czas pracy? 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 poprawnie, czy niektóre z nich były większe, mniejsze lub niepotrzebne? Czy masz jakieś środki poza sezonem Dokumentów Google, które udało Ci się wykorzystać?
Dwóch członków zespołu GloriousPickle PickleDoc SIG pracowało jako pisarze techniczni (jedna z nich w Europie, a druga w Argentynie). Dzięki temu mogliśmy oszacować nakład pracy i znaleźć podobne budżety projektów, porównując zadania z wcześniejszymi wersjami oferty pakietowej. Zostało nam też 1000 USD w postaci nieograniczonej kwoty sponsorowania z konferencji PicklePals w 2019 roku, które przekazaliśmy na ten projekt.
W wyniku nieprzewidzianych wydatków nasz pisarz techniczny mógł wynająć hotspot Wi-Fi na obszarze dotkniętym pożarami i utraconą dostępem do internetu w swoim domu. Poza tym rozesłaliśmy do uczestników mniej koszulek niż zakładaliśmy, więc udało się wyrównać wyniki.
Zdecydowaliśmy się też wynagrodzić współtwórczynię kanału GloriousPickle, @Piccalily (która kiedyś była profesjonalną edytorką tekstu w swoim wolnym życiu), za pomoc w edycji i korygowaniu dokumentacji przygotowanej przez tego artystę.
uczestników
Kto pracował nad tym projektem (użyj nazw użytkowników, jeśli uczestnicy o to proszą)? Jak udało Ci się znaleźć i zatrudnić scenarzystę technicznego? Jak udało Ci się znaleźć innych wolontariuszy lub płacących uczestników? Jakie role pełniły te osoby? Czy ktoś zrezygnował? Czego udało Ci się dowiedzieć o rekrutacji, komunikacji i zarządzaniu projektami?
Główny zespół pracujący nad tym projektem:
- @Dillicious, @KimChiCook (PickleDoc SIG)
- @Piccalily (edytor_tekstu)
- @GherKen, @VinegarViv (pomoc dla administratorów, GPPSC)
- @BBChips, @GloriousPicklePat (specjaliści w różnych dziedzinach)
- Sam Scribe (autor techniczny)
Znaleźliśmy Sama Scribe z listy repozytorium Sezonu Dokumentów Google na GitHubie. Uznaliśmy, że ich doświadczenie (prace dla dziennikarza kulinarnego oraz tworzenie dokumentacji do stron internetowych) pasuje do naszego projektu. Sam uczestniczył co 2 tygodnie w spotkaniu PickleDoc SIG i omawiał z nami cały projekt, przedstawiając kilka bardzo cennych sugestii, które zostały uwzględnione w ofercie. Skontaktowaliśmy się również z dwoma innymi twórcami technicznymi znanymi nam w sieciach członków SIG, ale żaden z nich nie był dostępny w czasie trwania programu.
Strefa czasowa Sama pokrywała się tylko przez kilka godzin z większością członków PickleDoc SIG, dlatego na naszym forum dyskusyjnym zaprosiliśmy selektorów ze swojej strefy czasowej, którzy byli obeznani z procesem dodawania składników. @BBChips odpowiadała na pytania Sama i pomagała znaleźć innych ekspertów w razie potrzeby. Zespół @GloriousPicklePat również chciał pomóc Samowi zrozumieć architekturę narzędzia i możliwych komunikatów o błędach z interfejsu API oraz zapewnił pomoc GitHubowi i git.
Niestety w trakcie programu @VinegarViv musiało zrezygnować z udziału w nim z powodów osobistych. @GherKen, członek programu GPPSC, zajął się kwestiami administracyjnymi i płatnościami.
Po kilku niewykorzystanych pytaniach (GloriousPickle używa bezpłatnej instancji Slacka, a czasem dyskusja toczy się tak szybko, że tracimy rozmowy z powodu limitu archiwów). Dowiedzieliśmy się, że należy zachować listę aktywnych pytań w udostępnionym dokumencie (użyliśmy udostępnionego dokumentu Google). Członkowie zespołu PickleDocuments SIG sprawdzili ją przed każdym spotkaniem i upewnili się, że uzyskali odpowiedzi przed końcem spotkania. Sam mógł skontaktować się z @BBChips bezpośrednio w sprawie pilnych pytań.
Współpraca z Samem i Samem była dla nas bardzo udana. Poza zaktualizowaniem dokumentacji GloriousPickle okazało się, że nawet bardzo go pilnują.
Oś czasu
Przedstaw krótko harmonogram realizacji projektu (podaj szacowaną datę zakończenia lub pośrednie etapy, jeśli projekt jest w trakcie jego realizacji).
Gdy czekaliśmy na ogłoszenie uczestników programu Sezon Dokumentów Google, członkowie zespołu PickleDocuments SIG szukali wszystkich poprzednich prac, które naszym zdaniem byłyby przydatne dla Sama. W ciągu miesiąca zdobyliśmy kilka informacji z wcześniejszych działań związanych z aktualizacją dokumentacji, która się wstrzymała. Przeanalizowaliśmy też fragmenty materiałów z kontroli dojrzałości dokumentacji w repozytorium Google opendocs.
Gdy otrzymaliśmy dobrą wiadomość o wybraniu programu Sezon Dokumentów Google, Sam i komisja PickleDoc SIG spotkały się i ustaliły ramowy harmonogram:
| Etap | Ukończony przez |
|---|---|
| Przejrzyj kontrolę dokumentów | 7 maja |
| Dziennik tarcia 3 – przypadki użycia | 14 maja |
| Przeglądaj dzienniki problemów z @GloriousPicklePat i @BBChips, odpowiadaj na pytania. | 28 maja |
| Pierwsza wersja robocza zaktualizowanych dokumentów – przypadek użycia 1 | 25 czerwca |
| Wersja robocza przypadku użycia 1 sprawdzona przez @GloriousPicklePat i @KimChiCook | 2 lipca |
| Pierwsza wersja robocza 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 – przypadek użycia 3 | 9 lipca |
| Przykład zastosowania 3 w wersji roboczej sprawdzony przez @Dillicious i @KimChiCook | 16 lipca |
| Wszystkie zapytania z odpowiedziami we wszystkich przypadkach użycia | 30 lipca |
| Większość pracowników PickleDokumenty SIG była na wakacjach 1–20 sierpnia | -- |
| Rozpocznij testowanie nowych dokumentów w społeczności (dokumenty publikowane jako wersje robocze w witrynie GloriousPickle) | 21 sierpnia |
| Dołączono opinię z testu | 10 września |
| Kopiuj i sprawdzaj nowe dokumenty | 17 września |
| Stan wersji roboczej dokumentów został usunięty i oficjalnie udostępniono dokumenty | 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 poświęci 10–15 godzin tygodniowo na pracę nad projektem. Jan przechowujeł dane o spędzonym czasie, średnio 11,5 godziny na tydzień.
Wyniki
Co zostało utworzone, zaktualizowane lub zmodyfikowane w inny sposób? Podaj linki do opublikowanej dokumentacji, jeśli są dostępne. Czy w ofercie pakietowej znajdują się treści, które nie zostały utworzone? Wymień je też.
Pełne instrukcje dla użytkownika omówiono w trzech głównych przypadkach 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
W tych przewodnikach znajdują się też nowe szablony żądań pull, które ułatwiają publikowanie treści.
Dodatkowo w ramach projektu Sam stworzył mały glosariusz Pickle'a z poznanymi terminami, który został opublikowany w witrynie projektu GloriousPickle.
Do naszej witryny wiki dodaliśmy instrukcje aktualizowania tych instrukcji dla użytkowników.
Uwzględniliśmy także ściągawkę dla nowych użytkowników GitHuba, która pomoże im w korzystaniu z naszych procesów i narzędzi, ale gdy spojrzeliśmy na dostępne zasoby, udało nam się utworzyć ściągawkę do innego projektu.
Wskaźniki
Jakie wskaźniki zostały wybrane do pomiaru powodzenia projektu? Czy udało Ci się zebrać te dane? Czy wskaźniki były skorelowane z oczekiwanymi wynikami projektu? Czy od czasu oferty pakietowej zmieniły się Twoje dane?
W propozycji zaproponowaliśmy 2 rodzaje danych:
- liczbę żądań pull związanych ze składnikami
- liczba żądań pull od nowych współtwórców
We wrześniu (pierwszy pełny miesiąc od opublikowania wersji roboczej dokumentacji) odnotowaliśmy 5-procentowy wzrost liczby żądań pull dotyczących składników (z 20 sierpnia do 21 września) oraz 3 nowych użytkowników, którzy przesłali łącznie 4 żądania pull (w porównaniu z 2 nowymi współtwórcami, którzy w sierpniu przesłali 2 żądania pull). Planujemy co miesiąc śledzić te dane.
Od 1 stycznia będziemy też śledzić liczbę współtwórców, którzy przesłali więcej niż 3 treści, począwszy od kwartału po opublikowaniu dokumentacji.
Podobno nowa dokumentacja pozwoliła nowym współtwórcom na dodawanie do bazy danych składników GloriousPickle – jednego z nowych współtwórców wspomnianych w komentarzu pod adresem swojego PR, które już wypróbował, ale nie ukończył aktualizacji, ponieważ nie rozumie procesu.
Analiza
Co poszło dobrze? Co było nieoczekiwane? Z jakimi przeszkodami się spotkałeś(-aś)? Czy uważasz swój projekt za udany? Dlaczego? (jeśli jest jeszcze za wcześnie, by wyjaśnić, kiedy będziesz w stanie ocenić sukces projektu).
Jesteśmy bardzo zadowoleni z rezultatu projektu Sezon Dokumentów Google i uznamy go za sukces. Nowa dokumentacja jest jasna i pomocna. Zauważyliśmy też wzrost liczby żądań pull związanych ze składnikami oraz liczby tych żądań od nowych współtwórców.
Byliśmy również zadowoleni, że prawie cała społeczność GloriousPickle zaangażowała się w zaangażowanie, przesyłając opinie na temat pierwotnej propozycji i testując nowe dokumenty w wersji roboczej.
Napotkaliśmy kilka niespodziewanych przeszkód — jesteśmy wdzięczni, że pożary u siebie w stanie Sama nie spowodowały żadnych większych szkód niż brak dostępu do internetu. Jest nam też przykro, że brakuje @VinegarViv w projekcie. Życzymy jej i jej rodzinie wszystkiego najlepszego i mamy nadzieję, że wkrótce znowu się zobaczymy.
Przed rozpoczęciem pracy nad dokumentacją Sama nie zdawaliśmy sobie sprawy z tego, jak wiele terminów i akronimów związanych z ogródkami nie znamy dla osoby uczestniczącej w naszym projekcie, która nie ma odpowiedniej wiedzy. Postanowił jednak przygotować listę wszystkich nieznanych terminów i zdefiniować je na podstawie własnych badań oraz prosząc członków społeczności o wyjaśnienia i źródła. Słowniczek ten będzie bardzo pomocny w przygotowywaniu członków społeczności tego typu w przyszłości.
Podsumowanie
W 2–4 akapitach podsumuj doświadczenia związane z projektem. Podkreśl swoją nabytą wiedzę i wyjaśnij, co Twoim zdaniem można zrobić inaczej w przyszłości. Jakich rad możesz dać innym projektom, które próbują rozwiązać podobny problem przy użyciu dokumentacji?
Krótko mówiąc, nasze wrażenia były kiczowate. Zrealizowaliśmy nasze zadania z dokumentacją, a wskaźniki są zgodne z naszymi celami.
W dużym stopniu o sukcesie tego projektu przyczyniło się to, że współpracowaliśmy z naszym pisarzem technicznym, Samem Scribe. [Nie jestem autorem tego tekstu—Sam] Chociaż Sam nie miał doświadczenia w pobieraniu i nagrywaniu w serwisie GitHub, jako doświadczony pisarz techniczny z łatwością zanurkował się w nowym zagadnieniu, zadawał pytania i szukał informacji. Sam szybko uchwycił nie tylko nasze narzędzia projektowe (do śledzenia pracy używamy tablicy kanban), ale też nasze żarty z pikle. Cieszymy się, że Jan złapał robaka i zapewniliśmy go w naszej społeczności.
Innym projektom zalecamy:
- Oferty powinny być krótkie i łatwe do zarządzania. (Chcieliśmy dołączyć do naszego szacunku dokumentację dotyczącą korzystania z naszego narzędzia do szacowania ilości przemysłowych maszyn do marynowania wsadowego, ale pominęliśmy ją tylko dlatego, że jeden z członków naszej społeczności głęboko zaangażowany w proces open source maszyn do ogórków chciał pisać doktorat w trakcie programu). W końcu mieliśmy za dużo pracy, żeby Sam się zajął.
- Szukaj autora tekstów technicznych, aby skorzystać ze swojej sieci kontaktów. Poproś wszystkich członków społeczności o rekomendacje. Chociaż udało nam się znaleźć Sama w sezonie Google Dokumentów na GitHubie, czuliśmy się pewnie we współpracy z nim, bo w okresie przesyłania zgłoszeń rozmawialiśmy z kilkoma osobami.
- Powitaj w swojej społeczności swojego autora technicznego. Samuel poinformował nas, że entuzjastyczne podejście zespołu GloriousPicklers ułatwiło zadawanie pytań.
- Pomóż swojemu pisarzowi technicznemu zdobyć umiejętności open source. Sam nigdy wcześniej nie korzystał z git, ale po zapoznaniu się z kilkoma samouczkami szybko nabrał dla niego tempa. Początkowo Sam obawiał się, ile opinii otrzymają od społeczności i jak je włączyć, ale model „ogólnego konsensusu” naszej społeczności („konsensusu, który zostaje osiągnięty, gdy wszystkie problemy są rozwiązane, a niekoniecznie przyzwyczajony”) sprawił, że Sam był pewny swojej wiedzy technicznej na temat pisania krytyki.
Dodatek
Jeśli masz inne materiały, do których chcesz podać link (na przykład umowę o współpracy z autorem technicznym, którą chcesz udostępnić), szablony do projektu dokumentacji lub inne otwarte zasoby dokumentacji, możesz je tutaj umieścić i podać link do nich. Załącznik to także dobre miejsce na listę linków do używanych przez Ciebie narzędzi i zasobów do dokumentacji. Możesz też dodać podziękowanie lub podziękowania, które mogą nie mieścić się w powyższych sekcjach.
Poświadczenia
Nasz zespół pragnie wymienić następujące osoby i cechy:
- @Dillicious chciałaby podziękować swojemu partnerowi i również muzyce hip-hopowej o niskiej jakości
- @KimChiCook chciałby podziękować jego twórcy 할머니 za nauczenie go, jak pikantować
- @Piccalily pragnie podziękować Chicago Manual of Style Online
- @GherKen chciałby podziękować swoim trójce dzieci za zjedzenie wszystkich przyrządzanych pikli
- @VinegarViv chce podziękować pozostałym członkom zespołu za umożliwienie jej zrezygnowania
- @BBChips chce podziękować za najlepsze dostępne jedzenie bez pikantności, czyli wafle karmelowe Tunnock.
- @GloriousPicklePat pragnie podziękować grupie PickleDokumentacja SIG za skorzystanie z tego projektu
- Sam Scribe pragnie podziękować całej społeczności GloriousPickle, a zwłaszcza tym selektorom, którzy wysyłali słoiki na słoiki w okresie niedoboru słoików w lecie 2021 roku, zaczynając od wyprawy po pyszne pikle.