Season of Docs to program zrównoważonego rozwoju zarządzany przez biuro Google Open Source Programs Office. Cele programu Season of Docs:
- wspieranie projektów open source w rozwiązywaniu problemów z dokumentacją;
- umożliwianie autorom dokumentacji technicznej zdobywania doświadczenia w projektach open source;
- zwiększanie świadomości na temat open source, dokumentacji i pisania technicznego;
- gromadzenie i udostępnianie informacji o skutecznych wskaźnikach w dokumentacji open source.
Więcej informacji o programie Season of Docs znajdziesz na jego stronie internetowej.
Informacje o programie w 2022 r.
Jak działa program Season of Docs
W programie Season of Docs organizacje zgłaszają się, przesyłając propozycję projektu. Propozycja projektu zawiera:
- informacje o organizacji;
- opis problemu, z którym boryka się projekt;
- informacje o tym, jak projekt wykorzysta dokumentację do rozwiązania problemu;
- informacje o tym, jak projekt będzie mierzyć skuteczność dokumentacji (wskaźniki);
- harmonogram prac;
- budżet projektu;
- dodatkowe informacje, np. o doświadczeniu organizacji w podobnych programach lub inne informacje, które pomogą administratorom programu Season of Docs zrozumieć projekt i problem.
Po przyjęciu do programu organizacje samodzielnie rekrutują i zatrudniają autorów dokumentacji technicznej. Program Season of Docs korzysta z platformy Open Collective do finansowania organizacji, a organizacje płacą autorom dokumentacji technicznej za pomocą tej platformy. Budżety projektów i płatności są przejrzyste. Budżety są uwzględnione w propozycjach projektów organizacji dostępnych na stronie Season of Docs, a płatności są widoczne na koncie Season of Docs Open Collective.
Uznaje się, że organizacje ukończyły program, gdy prześlą raport ze studium przypadku. W trakcie programu organizacje są też proszone o wypełnianie comiesięcznych ocen, a w ciągu roku po zakończeniu programu – 3 kwartalnych ankiet.
Najważniejsze informacje z 2022 r.
„Po opublikowaniu nowego dokumentu dzienna liczba wizyt w Casbin i Casdoor niemal się podwoiła, a współczynniki odrzuceń spadły o około 30%”. – Casbin
„Wspaniałym efektem tego projektu było obserwowanie, jak [nasi autorzy dokumentacji technicznej] awansują na stanowiska kierownicze w naszej społeczności. Obecnie oboje współtwórcy prowadzą spotkania grup roboczych i społeczności, a także biorą udział w projektowaniu i utrzymaniu naszych projektów”. – moja-global
„[GSoD] pomógł nam zrekrutować 2 utalentowanych autorów dokumentacji technicznej, co w normalnych warunkach jest bardzo trudne. Nadal aktywnie współtworzą oni OpenMined i świetnie nam się z nimi współpracuje”. – OpenMined
„Nowy podręcznik jest też znacznie łatwiejszy w użyciu dla początkujących w dziedzinie obliczeniowej spektrometrii mas. Aby to zilustrować: stypendium CZI obejmuje też stypendia dla osób z grup historycznie uprzywilejowanych, a niektórzy stypendyści wykorzystali nowy podręcznik OpenMS, aby szybko rozpocząć 6-tygodniowy staż, i wystawili mu pozytywne opinie”. – OpenMS
Podsumowanie danych z 2022 r.
W 2022 r. w ramach programu Season of Docs przyjęto 31 projektów spośród 67 zgłoszeń, a 30 projektów ukończyło program. Spośród 31 przyjętych organizacji 17 ponownie zgłosiło się do programu.
W 31 przyjętych projektach zatrudniono 58 autorów dokumentacji technicznej. Ponad 190 autorów dokumentacji technicznej wyraziło zainteresowanie udziałem w programie, dodając swoje dane kontaktowe i linki do portfolio w repozytorium GitHub programu Season of Docs.
W przypadku programu z 2022 r.:
- 100% organizacji pozytywnie oceniło proces składania wniosków.
- 100% organizacji pozytywnie oceniło dokumentację i treści na stronie programu.
- 93% organizacji pozytywnie oceniło program.
- 90% organizacji uznało, że ich projekt dokumentacji zakończył się sukcesem.
Informacje o organizacjach
Organizacje uczestniczące w programie Season of Docs 2022 reprezentowały różnorodne projekty open source. W grupie z 2022 r. znalazły się:
- narzędzia dla programistów, takie jak AsyncAPI i SpyderIDE
- języki programowania i frameworki, takie jak Julia, LFortran, R, i p5.js
- projekty naukowe, takie jak CERN-HSF i SymPy
- aplikacje dla użytkowników końcowych, takie jak Mautic, Open Food Facts, Talawa i Ushahidi
- projekty sprzętowe i robotyczne, takie jak ExpressLRS i Open-RMF;
- projekty związane z danymi, takie jak GeomScale, GeomStats, OpenMined i Weaviate;
- projekty związane z chmurą i infrastrukturą, takie jak cert-manager, NimbleEdge i Cilium.
Nie zbieraliśmy żadnych metadanych o projektach (takich jak data założenia, rozmieszczenie geograficzne współtwórców, liczba współtwórców czy wielkość bazy użytkowników).
Poprosiliśmy projekty o wskazanie, jakiej licencji open source używają.
Informacje o projektach dokumentacji
Problemy z dokumentacją
Główne problemy, które organizacje chciały rozwiązać za pomocą dokumentacji w ramach programu z 2022 r., to:
Pamiętaj, że organizacje mogły zgłaszać wiele problemów z dokumentacją. Więcej szczegółów znajdziesz na stronie z wynikami programu Season of Docs 2022 results page, na której znajdują się linki do pierwotnych propozycji projektów i pełnych studiów przypadku każdej organizacji.
Rodzaje utworzonej dokumentacji
W studiach przypadku z 2022 r. najczęściej wymienianym rodzajem dokumentacji były Instrukcje.
Inne rodzaje dokumentacji wymienione w studiach przypadku:
- Krótkie wprowadzenie
- Słowniczek
- Najczęstsze pytania
- Baza wiedzy
- Komponenty
- Treści na blogu i w mediach społecznościowych
- Przewodnik dla opiekunów
Niektóre z tych kategorii są niejasne, a pojedynczy projekt dokumentacji może zawierać wiele rodzajów dokumentacji lub funkcji.
Więcej szczegółów znajdziesz na stronie z wynikami programu Season of Docs 2022 results page, na której znajdują się linki do pierwotnych propozycji projektów i pełnych studiów przypadku każdej organizacji.
Budżety
Średnia kwota wniosku o budżet wyniosła 11 679 USD, a mediana – 12 150 USD. 5 organizacji poprosiło o najwyższe dostępne dofinansowanie (15 tys. USD) i je otrzymało, a 3 poprosiły o najniższe (od 5 tys. do 7 tys. USD).
Dane
W studiach przypadku projekty przedstawiły dane, których używały do oceny powodzenia projektów dokumentacji.
Najczęściej proponowane dane:
Inne proponowane dane:
- więcej próśb o scalenie i współtworzenia dokumentacji;
- więcej bezpośrednich opinii na stronach dokumentacji;
- czas spędzony na stronie;
- zgłoszone problemy (jako wskaźnik użycia);
- uczestnicy forów;
- liczba partnerów, wolontariuszy i integracji;
- zmniejszenie współczynnika odrzuceń;
- większa świadomość w społeczności.
Ze względu na krótki czas między zakończeniem projektów pisania technicznego a przesłaniem studiów przypadku większość uczestników programu z 2022 r. nie zdążyła zebrać wystarczającej ilości danych, aby w momencie przesyłania studiów przypadku stwierdzić, czy początkowe dane zostały osiągnięte.
Gdy w 2023 r. otrzymamy odpowiedzi na ankiety uzupełniające, zaktualizujemy ten raport, dodając informacje o tym, które projekty osiągnęły swoje dane lub je zmieniły.
Więcej szczegółów znajdziesz na stronie z wynikami programu Season of Docs 2022 results page, na której znajdują się linki do pierwotnych propozycji projektów i pełnych studiów przypadku każdej organizacji.
Współpraca z autorami dokumentacji technicznej
W ramach programu Season of Docs projekty mają samodzielnie rekrutować, przeprowadzać rozmowy kwalifikacyjne, zatrudniać i opłacać autorów dokumentacji technicznej. Autorzy dokumentacji technicznej mogą dodać się do katalogu prowadzonego przez Season of Docs w naszym repozytorium GitHub, ale pracownicy Season of Docs nie sprawdzają ani nie polecają autorów dokumentacji technicznej.
Sprawdzone metody zatrudniania autorów dokumentacji technicznej do projektów open source
Poprosiliśmy projekty o podzielenie się sprawdzonymi metodami rekrutacji, zatrudniania i współpracy z autorami dokumentacji technicznej. Najważniejsze zalecenia:
Rekrutacja
- Przeprowadzaj rozmowy kwalifikacyjne z mniejszą liczbą kandydatów i zamiast tylko sprawdzać CV, korzystaj z sesji praktycznych na żywo.
- Większą wagę przywiązuj do umiejętności komunikacji pisemnej i ustnej niż do znajomości języka lub narzędzi projektu.
- Zadawaj bezpośrednie pytania o to, jak autor dokumentacji technicznej zdobędzie wiedzę w danej dziedzinie niezbędną do pracy nad Twoim projektem.
- Osoba, która jest entuzjastycznie nastawiona do misji Twojego projektu i podziela podstawowe wartości open source, z większym prawdopodobieństwem zachowa motywację przez cały projekt.
- Bądź otwarty na kandydatów z całego świata, ponieważ różnorodność punktów widzenia i doświadczeń pomoże Twojemu projektowi. Pamiętaj jednak, że jeśli autorzy i mentorzy będą w zbyt wielu strefach czasowych, utrzymanie dobrej komunikacji może wymagać dużo dodatkowego wysiłku.
Zatrudnianie
- Używaj umowy, która jasno określa wyniki, harmonogramy płatności i konkretne zobowiązania czasowe.
- Jeśli w Twoim projekcie jest wiele niewiadomych, uwzględnij etap odkrywania lub badań oddzielnie od tworzenia dokumentacji.
Koordynacja i komunikacja
- Prowadź dziennik spotkań, w którym zapisujesz decyzje, aby ułatwić wszystkim osobom pracującym nad projektem zrozumienie kontekstu i kolejnych kroków.
- Jasno określ, jak często i w jaki sposób ma się odbywać komunikacja, np. cotygodniowe rozmowy, codzienne e-maile lub aktualizacje stanu na czacie.
- Reaguj szybko i przekazuj jasne opinie, które zawierają nie tylko „co”, ale też „dlaczego”.
- Połącz autorów dokumentacji technicznej z szerszą społecznością, aby zapewnić im kontekst i umożliwić im dzielenie się swoją pracą.
Procesy i narzędzia
- Utwórz proces dokumentacji, który będzie trwał dłużej niż program Season of Docs i w którym będzie mogła uczestniczyć cała społeczność.
- Sprawdzanie dokumentacji zajmie co najmniej tyle czasu i będzie tak samo intensywne jak inspekcja kodu. Pamiętaj, aby przeznaczyć na to wystarczająco dużo czasu.
Niektóre zalecenia zostały zmienione i skrócone w celu uniknięcia wątpliwości.
Podobnie jak w programie z 2021 r. większość autorów dokumentacji technicznej w programie Season of Docs 2022 zgłosiła się bezpośrednio do organizacji, z którymi współpracowała.
Typowe problemy we współpracy z autorami dokumentacji technicznej
W programie z 2022 r. mniej projektów zgłosiło problemy ze współpracą z autorami dokumentacji technicznej. Największym problemem było to, że autorzy dokumentacji technicznej nie mogli ukończyć programu z powodu choroby, podjęcia pracy na pełny etat lub braku czasu.
Jeden projekt zgłosił, że jego projekt dokumentacji był zależny od prac wykonywanych w ramach Google Summer of Code, a zarządzanie tymi zależnościami było trudne. Inny projekt napotkał trudności, gdy sprzęt, który autor dokumentacji technicznej musiał udokumentować, został skonfiskowany przez Ministerstwo Obrony w kraju autora i nie można go było importować.
Ankiety uzupełniające
W maju, sierpniu i listopadzie 2023 r. uczestnicy programu z 2022 r. otrzymają 3 ankiety uzupełniające. Gdy otrzymamy wyniki, zaktualizujemy tę sekcję.
Przyszłe pytania
Jak zawsze, im więcej dowiadujemy się o dokumentacji w projektach open source, tym więcej chcemy się dowiedzieć.
W przyszłych edycjach programu chcemy:
- zbierać więcej metadanych projektu, aby szukać korelacji między wiekiem projektu, wielkością społeczności lub językiem a potrzebami w zakresie dokumentacji;
- analizować projekty dokumentacji, aby sprawdzić, czy można je uogólnić do postaci szablonów do udostępniania;
- opracować kryteria oceny przeprowadzania rozmów kwalifikacyjnych z autorami dokumentacji technicznej w projektach open source.
Chociaż mamy wiele pytań, na które chcielibyśmy znaleźć odpowiedzi, chcemy też szanować czas administratorów i opiekunów projektów open source, którzy biorą udział w programie Season of Docs. Najważniejszym celem programu jest wspieranie projektów w rozwiązywaniu problemów z dokumentacją.