Obecny etap:
opracowywanie dokumentacji. Sprawdź oś czasu.
Sezon Dokumentów to program zrównoważonego rozwoju zarządzany przez pakiet Google Open Source Programs Office. Cele Sezonu Dokumentów to:
- Pomoc w rozwiązywaniu problemów związanych z projektami open source dzięki dokumentacji
- Zapewnij pisarzom technicznym możliwość zdobycia doświadczenia w zakresie oprogramowania open source
- promowanie oprogramowania open source, dokumentacji i pisania technicznego;
- Gromadzenie i udostępnianie informacji na temat skutecznych wskaźników w dokumentacji open source
Więcej informacji o sezonie Dokumentów znajdziesz na stronie programu.
Omówienie programu na rok 2022
Jak działa sezon Dokumentów
W sezonie Dokumentów organizacje zgłaszają się, przesyłając propozycję projektu. Propozycja projektu obejmuje:
- Informacje o organizacji
- Opis problemu, z którym boryka się projekt
- w jaki sposób projekt wykorzysta dokumentację do rozwiązania problemu;
- Jak projekt będzie mierzyć skuteczność dokumentacji (dane)
- Harmonogram pracy
- Budżet projektu
- wszelkie dodatkowe informacje, na przykład doświadczenia organizacji w podobnych programach lub wszelkie inne informacje, które mogą pomóc administratorom Sezonu Dokumentów lepiej zrozumieć ich projekt i problem;
Po przyjęciu do programu organizacje rekrutują i zatrudniają bezpośrednio swoich specjalistów ds. technicznych. Sezon Dokumentów korzysta z Open Collective do finansowania organizacji, a organizacje przekazują twórcom treści o charakterze technicznym w ramach Open Collective. Budżety projektów i płatności są przejrzyste. Budżety są ujęte w propozycjach projektów organizacji, które są dostępne w witrynie Sezonu Dokumentów, a płatności są widoczne na koncie Open Collective w sezonie Dokumentów.
Uznaje się, że organizacja ukończyła program, jeśli prześle raport ze studium przypadku. Organizacje są również proszone o przeprowadzanie comiesięcznych ocen w trakcie programu oraz 3 ankiety kwartalne w ciągu roku po jego ukończeniu.
Najciekawsze w 2022 roku
„Po opublikowaniu nowego dokumentu dzienne wizyty w Casbin i Casdoor niemal się podwoiły, a współczynniki odrzuceń spadły o około 30%” – Casbin
„Wspaniałym wynikiem tego projektu była obserwowanie, jak [nasi autorzy techniczni] wkraczają na stanowiska kierownicze w naszej społeczności. Obaj współtwórcy prowadzą obecnie spotkania grup roboczych i społeczności, a także przyczyniają się do projektowania i utrzymania naszych projektów”. – moja-global
„[GSoD] pomógł nam zatrudnić 2 utalentowanych autorów oprogramowania, co jest bardzo trudne w przypadku regularnych instalacji, którzy nadal aktywnie uczestniczą w programie OpenMined i z którymi mamy świetne doświadczenie” – OpenMined.
„Dodatkowo nowa instrukcja obsługi jest znacznie łatwiejsza w obsłudze obliczeniowej spektrometrii mas dla początkujących. Dla przykładu: grant CZI zapewnia też stypendia dla osób w przeszłości gorzej sytuowanych. Niektórzy uczestnicy skorzystali z nowego podręcznika OpenMS, aby rozpocząć 6-tygodniowy okres stażu, i ocenili go pozytywnie” – OpenMS.
Podsumowanie danych z 2022 r.
W 2022 roku do programu Sezon Dokumentów przyjęto 31 projektów z 67 zgłoszeń, a 30 projektów z powodzeniem ukończyło program. Spośród 31 zaakceptowanych organizacji 17 zgłosiło się ponownie.
W ramach 31 przyjętych projektów zatrudniono 58 twórców technicznych. Ponad 190 twórców treści technicznych wykazało zainteresowanie programem, dodając swoje dane kontaktowe i linki do swoich portfolio w repozytorium Sezon Dokumentów na GitHubie.
W przypadku programu na rok 2022:
- 100% organizacji ma pozytywne doświadczenia z procesem przesyłania zgłoszeń.
- 100% organizacji jest pozytywnie ocenianych z uwzględnieniem dokumentacji i treści dostępnych w witrynie programu.
- 93% organizacji pozytywnie oceniasz program
- 90% organizacji uznało, że ich projekt dokumentacji zakończył się sukcesem
Informacje o organizacjach
Organizacje uczestniczące w sezonie Dokumentów 2022 reprezentowały różne projekty open source. Grupa w 2022 r. obejmowała:
- narzędzia dla programistów, takie jak AsyncAPI i SpyderIDE;
- języki i platformy programowania, np. Julia, LFortran, R czy p5.js.
- projekty naukowe, takie jak CERN-HSF czy SymPy;
- Aplikacje dla użytkowników, takie jak Mautic, Open Food Facts, Talawa i Ushahidi
- projekty związane ze sprzętem i robotyką, np. ExpressLRS i Open-RMF.
- Projekty danych, takie jak GeomScale, GeomStats, OpenMined i Weaviate
- projekty w chmurze i infrastrukturze, takie jak cert-manager, NimbleEdge czy Cilium;
Nie zebraliśmy żadnych metadanych o projektach (takich jak data założenia, rozkład geograficzny współtwórców, liczba współpracowników czy wielkość grupy użytkowników).
Poprosiliśmy projekty o wskazanie użytej licencji open source.
Informacje o projektach z dokumentacją
Problemy z dokumentacją
Najważniejsze problemy, które organizacje chciały rozwiązać za pomocą dokumentacji w ramach programu na 2022 rok, to:
Pamiętaj, że organizacje mogą zgłaszać wiele problemów z dokumentacją. Więcej informacji znajdziesz na stronie wyników dotyczącej sezonu Dokumentów 2022, która zawiera linki do oryginalnych propozycji projektów oraz pełnych studiów przypadków dotyczących poszczególnych organizacji.
Rodzaje tworzonych dokumentów
Dokumentacja z instrukcjami to najczęściej omawiany typ dokumentacji w studiach przypadków w 2022 roku.
W studiach przypadków wspomniano też o innych rodzajach dokumentów:
- Krótkie wprowadzenie
- Glosariusz
- Najczęstsze pytania
- Baza wiedzy
- Komponenty
- Treści na blogu lub w mediach społecznościowych
- Przewodnik dla opiekuna
Niektóre z tych kategorii są przybliżone, a pojedynczy projekt dokumentacji może zawierać wiele typów dokumentacji lub funkcji.
Więcej informacji znajdziesz na stronie wyników dotyczącej sezonu Dokumentów 2022, która zawiera linki do oryginalnych propozycji projektów oraz pełnych studiów przypadków dotyczących poszczególnych organizacji.
Budżety
Średnia prośba o budżet wynosiła 11 679 zł, a mediana – 12 150 zł. Pięć organizacji zgłosiło się do wniosku i otrzymało najwyższy dostępny grant (15 tys. USD), a 3 – najniższy (od 5 tys. USD do 7 tys. USD).
Dane
Projekty zostały przedstawione w studiach przypadków, a dane używane do oceny sukcesu projektów dokumentacyjnych.
Najczęściej proponowane dane to:
Inne proponowane dane to m.in.:
- Więcej próśb o wniosek o udostępnienie dokumentacji/więcej darowizn
- Bardziej bezpośrednia opinia na stronach z dokumentacją
- Czas spędzony na stronie
- Zgłoszone problemy (jako serwer proxy do użytku)
- Uczestnicy na forach
- Liczba partnerów/wolontariuszy/integracji
- Zmniejszony współczynnik odrzuceń
- Większa świadomość w społeczności.
Ze względu na krótki czas między zakończeniem tworzenia projektów technicznych a przesłaniem studiów przypadków większość osób z kohorty z 2022 roku nie była w stanie zebrać wystarczającej ilości danych w momencie przesyłania studiów przypadków, aby określić, czy udało się osiągnąć ich wstępne wartości.
W miarę uzyskiwania odpowiedzi na kolejne ankiety w 2023 r. będziemy aktualizować ten raport, dodając informacje o projektach, które osiągnęły odpowiednie wskaźniki lub zmodyfikowały wskaźniki.
Więcej informacji znajdziesz na stronie wyników dotyczącej sezonu Dokumentów 2022, która zawiera linki do oryginalnych propozycji projektów oraz pełnych studiów przypadków dotyczących poszczególnych organizacji.
Współpraca z twórcami technicznymi
W ramach programu Sezon Dokumenty oczekujemy bezpośredniej rekrutacji, rozmów kwalifikacyjnych oraz wynagrodzenia dla pisarzy technicznych. Autorzy techniczni mogą dodawać się do katalogu obsługiwanego przez sezon dokumentów w naszym repozytorium Sezonu Dokumentów, ale nie weryfikują go ani nie polecają autorów treści technicznych.
Sprawdzone metody zatrudniania pisarzy technicznych do projektów open source
Poproszono o wykorzystanie sprawdzonych metod rekrutacji, zatrudniania i współpracy z pisarzami ds. technicznych. Najważniejsze rekomendacje:
Rekrutacja
- Przeprowadzaj rozmowy kwalifikacyjne z mniejszą liczbą kandydatów i korzystaj z próbnej sesji na żywo zamiast sprawdzania CV
- Oceń umiejętności w zakresie komunikacji ustnej i pisemnej nad biegłością w języku lub narzędziach używanych w projekcie
- Zadawaj bezpośrednie pytania o to, w jaki sposób autor techniczny uzyska wiedzę z zakresu niezbędnego do pracy nad Twoim projektem.
- Osoby, które pasjonują się misją Twojego projektu i postępują zgodnie z podstawowymi wartościami dotyczącymi oprogramowania open source, łatwiej będzie utrzymać motywację podczas całego projektu.
- Przyjmuj zgłoszenia z całego świata, ponieważ różnorodność punktów widzenia i środowiska pomogą w realizacji projektu. Pamiętaj jednak, że bycie scenarzyści i mentorów ze zbyt wielu sprzecznych stref czasowych może wymagać wiele dodatkowych nakładów pracy.
Zatrudniamy
- Używaj umowy, która jasno określa warunki dostawy, harmonogram płatności i konkretne zobowiązania czasowe.
- Jeśli Twój projekt zawiera dużo niewiadomych, uwzględnij etap odkrywania lub badań niezależnie od tworzenia dokumentacji.
Koordynacja i komunikacja
- Prowadź zapisy w dzienniku spotkań, aby ułatwić wszystkim osobom pracującym nad projektem zrozumienie kontekstu i dalszych kroków.
- Jasno określ, czego oczekujesz i jak często będą wysyłane połączenia co tydzień, codzienne e-maile czy aktualne informacje o stanie na czacie
- Reaguj i wyraźnie przekazuj informacje zwrotne z pytaniem „dlaczego?” i „co”, a nie tylko „dlaczego”.
- Nawiąż kontakt z szerszą społecznością autorów treści technicznych, aby zapewnić im szerszy kontekst i uatrakcyjnić ich pracę.
Procesy i narzędzia
- Opracuj proces dokumentacji, który będzie trwały dłużej niż zakończenie programu „Sezon of Dokumentów” i że cała społeczność będzie mogła przyczyniać się do jego realizacji.
- Weryfikacja dokumentacji trwa co najmniej tyle samo czasu jak weryfikacja kodu. Upewnij się, że przeznacz na nią odpowiednią ilość czasu.
Niektóre rekomendacje zostały zmienione i skrócone, aby były bardziej przejrzyste.
Podobnie jak w przypadku programu na 2021 rok, większość autorów prac technicznych w sezonie Dokumentów 2022 zgłosiło się bezpośrednio do organizacji, z którymi pracowali.
Typowe problemy ze współpracą z twórcami technicznymi
W 2022 roku mniej projektów zgłaszało problemy ze współpracą ze specjalistami ds. technicznych. Największy problem stanowili pisarze techniczni, którzy nie mogli ukończyć programu ze względu na chorobę, podjęcie pracy na pełny etat lub brak możliwości dotrzymania określonego czasu.
W jednym z projektów informowano, że projekt dokumentacji był uzależniony od prac w ramach programu Google Summer of Code, a zależności te były trudne do zarządzania. W innym projekcie wystąpiły problemy, gdy sprzęt potrzebny do udokumentowania pracy pisarza technicznego został skonfigurowany przez Ministerstwo Obrony w kraju pisarza i nie można go było zaimportować.
Ankiety dodatkowe
Uczestnicy 2022 roku w maju, sierpniu i listopadzie 2023 roku otrzymają 3 kolejne ankiety. Będziemy aktualizować tę sekcję w miarę pojawiania się kolejnych wyników.
Przyszłe pytania
Im więcej dowiadujemy się o dokumentacji na licencji open source, tym więcej chcemy się dowiedzieć.
Mamy nadzieję, że w kolejnych sezonach:
- Zbierz więcej metadanych projektu, aby znaleźć korelacje między wiekiem projektu, wielkością społeczności lub potrzebami w zakresie języka i dokumentacji.
- Przeanalizuj projekty dokumentacji, aby sprawdzić, czy można je uogólnić w szablony z możliwością udostępniania
- Opracowanie oceny cząstkowej na potrzeby rozmów z pisarzami technicznymi w projektach open source
Jest wiele pytań, które chcemy odpowiedzieć, ale jednocześnie szanujemy czas administratorów projektu open source i opiekunów, którzy uczestniczą w tym sezonie. Głównym priorytetem programu jest wspieranie projektów w rozwiązywaniu problemów przy użyciu dokumentacji.