Aktualna faza:
opublikowano studia przypadków. Zobacz oś czasu.
Season of Docs to program zrównoważonego rozwoju zarządzany przez Google Open Source Programs Office. Cele Season of Docs:
- zapewniać wsparcie dla projektów open source w celu rozwiązywania problemów z dokumentacją projektu;
- Dawanie autorom technicznym możliwości zdobywania doświadczenia w zakresie oprogramowania open source
- zwiększać świadomość dotyczącą open source, dokumentacji i pisania technicznego;
- Zbieranie i udostępnianie informacji o skutecznych danych w dokumentacji dotyczącej oprogramowania open source
Więcej informacji o programie Season of Docs znajdziesz na jego stronie.
Omówienie programu na rok 2022
Jak działa Season of Docs
W ramach Sezonu 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;
- jak projekt będzie używać dokumentacji, aby rozwiązać problem;
- Jak projekt będzie mierzyć skuteczność dokumentacji (dane)
- harmonogram pracy;
- budżet projektu,
- wszelkie dodatkowe informacje, takie jak doświadczenie organizacji w podobnych programach lub inne informacje, które pomogą administratorom w zrozumieniu projektu i problemu;
Po przyjęciu do programu organizacje samodzielnie rekrutują i zatrudniają własnych autorów treści technicznych. Sezon Dokumentów korzysta z Open Collective do finansowania organizacji, a organizacje płacą autorom technicznym za pośrednictwem Open Collective. Budżety i płatności za projekty 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 Open Collective w ramach Season of Docs.
Organizacje są uznawane za uczestniczące w programie po przesłaniu raportu z case study. Organizacje są też proszone o przeprowadzanie comiesięcznych ocen w trakcie trwania programu oraz 3 cokwartalnych ankiet kontrolnych w ciągu roku po zakończeniu programu.
Najciekawsze wydarzenia w 2022 r.
„Po opublikowaniu nowego dokumentu liczba codziennych wizyt na stronach Casbin i Casdoor prawie się podwoiła, a wskaźnik odrzuceń zmalał o około 30%”. – Casbin
„Wspaniałym efektem tego projektu było to, że nasi autorzy tekstów technicznych zaczęli pełnić w naszej społeczności role liderów. Obaj uczestnicy prowadzą teraz spotkania grup roboczych i społeczności, a także uczestniczą w projektowaniu i utrzymywaniu naszych projektów”. – moja-global
„[GSoD] pomogła nam w rekrutacji 2 utalentowanych technicznych autorów, co jest bardzo trudne w standardowej konfiguracji. Ci autorzy nadal aktywnie pracują nad OpenMined i mamy z nimi świetne doświadczenia”. – OpenMined
„Ponadto nowy podręcznik jest znacznie przystępniejszy dla początkujących użytkowników komputerowej spektrometrii masowej. Aby zilustrować ten punkt, należy wspomnieć, że grant CZI obejmuje również stypendia dla osób, które historycznie były w gorszej sytuacji. Niektórzy beneficjenci wykorzystali nowy podręcznik OpenMS, aby rozpocząć 6-tygodniowy staż, i wyrazili pozytywne opinie na jego temat” – OpenMS
Dane podsumowania z 2022 r.
W 2022 r. w ramach programu Season of Docs przyjęliśmy 31 projektów spośród 67 aplikacji, a 30 z nich ukończyło program. Spośród 31 zaakceptowanych organizacji 17 to organizacje, które wcześniej już się zgłaszały.
W 31 zaakceptowanych projektach zatrudniono 58 pisarzy technicznych. Ponad 190 autorów tekstów technicznych wyraziło zainteresowanie udziałem w programie, dodając swoje dane kontaktowe i linki do portfolio w repozytorium GitHub Season of Docs.
W programie z 2022 r.:
- 100% organizacji pozytywnie oceniło proces rejestracji
- 100% organizacji pozytywnie oceniło dokumentację lub treści na stronie programu
- 93% organizacji oceniło udział w programie pozytywnie
- 90% organizacji uważa, że ich projekt dokumentacji był udany
Organizacje
Organizacje biorące udział w sezonie Dokumentów 2022 reprezentowały różnorodną gamę projektów open source. Grupa z 2022 r. obejmowała:
- narzędzia programistyczne, takie jak AsyncAPI i SpyderIDE;
- języki i platformy programistyczne, takie jak Julia, LFortran, R i p5.js;
- projekty naukowe, takie jak CERN-HSF i SymPy;
- aplikacje dla użytkowników, takie jak Mautic, Open Food Facts, Talawa i Ushahidi;
- projekty związane ze sprzętem i robotyką, takie jak ExpressLRS i Open-RMF;
- projekty danych, takie jak GeomScale, GeomStats, OpenMined i Weaviate;
- projekty dotyczące chmury i infrastruktury, takie jak cert-manager, NimbleEdge i Cilium.
Nie gromadziliśmy żadnych metadanych dotyczących projektów (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, której licencji open source używają.
Informacje o projektach dokumentacji
Problemy z dokumentacją
Najczęstsze problemy, które organizacje chciały rozwiązać dzięki dokumentacji w programie z 2022 r., to:
Pamiętaj, że organizacje mogą zgłaszać wiele problemów z dokumentacją. Więcej informacji znajdziesz na stronie z wynikami konkursu Season of Docs 2022, na której znajdziesz linki do oryginalnych propozycji projektów i pełnych historii klientów poszczególnych organizacji.
Typy tworzonej dokumentacji
W studiach przypadków z 2022 r. najczęściej wspominano dokumentację instruktażową.
Inne typy dokumentacji wymienione w przypadkach zastosowań:
- Krótkie wprowadzenie
- Słowniczek
- Najczęstsze pytania
- Baza wiedzy
- Komponenty
- Treści bloga/mediów społecznościowych
- Przewodnik dla administratorów
Niektóre z tych kategorii są nieostre, a jeden projekt dokumentacji może zawierać wiele typów lub funkcji dokumentacji.
Więcej informacji znajdziesz na stronie z wynikami konkursu Season of Docs 2022, na której znajdziesz linki do oryginalnych propozycji projektów i pełnych historii klientów poszczególnych organizacji.
Budżety
Średnia prośba o budżet wynosiła 11 679 USD, a mediana – 12 150 USD. Pięć organizacji poprosiło o największy dostępny grant (15 tys. USD) i go otrzymało, a trzy o najmniejszy (od 5 do 7 tys. USD).
Dane
W projektach opisanych w tych studiach przypadków podano dane, których używali do oceny skuteczności projektów dokumentacji.
Najczęściej proponowane dane to:
Inne proponowane dane:
- Więcej żądań pobierania dokumentacji i wkładu
- bezpośrednie opinie na stronach dokumentacji,
- Czas spędzony na stronie
- zgłoszone problemy (jako zastępstwo za użycie)
- Uczestnicy na forach
- Liczba partnerów/wolontariuszy/integracji
- Obniżony współczynnik odrzuceń
- Zwiększenie świadomości w społeczności.
Z powodu krótkiego czasu między ukończeniem projektów związanych z tworzeniem tekstów technicznych a przesłaniem studiów przypadków większość uczestników edycji 2022 nie była w stanie zebrać wystarczającej ilości danych w momencie przesyłania swoich studiów, aby ustalić, czy udało im się osiągnąć początkowe wskaźniki.
Gdy w 2023 r. zaczniemy otrzymywać odpowiedzi na kolejne ankiety, zaktualizujemy ten raport, aby dodać do niego informacje o tym, które projekty osiągnęły swoje dane lub je zmodyfikowały.
Więcej informacji znajdziesz na stronie z wynikami konkursu Season of Docs 2022, na której znajdziesz linki do oryginalnych propozycji projektów i pełnych historii klientów poszczególnych organizacji.
Współpraca z pisarzami technicznymi
W ramach programu „Sezon na dokumenty” projekty muszą samodzielnie rekrutować, przeprowadzać rozmowy kwalifikacyjne, zatrudniać i płacić pisarzom technicznym. Autorzy tekstów technicznych mogą dodawać się do katalogu prowadzonego przez Season of Docs w naszym repozytorium GitHub, ale pracownicy Season of Docs nie weryfikują ani nie polecają autorów tekstów technicznych.
Sprawdzone metody zatrudniania autorów tekstów technicznych do projektów typu open source
Uczestnicy projektu mieli za zadanie podzielić się sprawdzonymi metodami rekrutacji, zatrudniania i współpracy z zespołem autorów treści technicznych. Najlepsze rekomendacje to:
Rekrutacja
- Zamiast przeglądać tylko CV, przeprowadź rozmowę kwalifikacyjną z mniejszą liczbą kandydatów i wykorzystaj sesję praktyczną na żywo.
- większą wagę przywiązuje do umiejętności komunikacji pisemnej i ustnej niż do znajomości języka lub narzędzi projektu;
- Zadaj pytania o to, jak autor tekstów technicznych zamierza zdobyć wiedzę specjalistyczną niezbędną do pracy nad Twoim projektem.
- Osoba, która jest zaangażowana w misję projektu i dzieli podstawowe wartości open source, prawdopodobnie będzie bardziej zmotywowana do pracy nad projektem.
- Przyjmij kandydatów z całego świata, ponieważ różnorodność punktów widzenia i tła pomoże Twojemu projektowi. Pamiętaj jednak, że praca z tak dużą liczbą pisarzy i mentorów w różnych strefach czasowych może wymagać sporo dodatkowego wysiłku, aby utrzymać dobrą komunikację.
Zatrudniamy
- Użyj umowy, która jasno określa wyniki, harmonogramy płatności i określone zobowiązania czasowe.
- Jeśli Twój projekt zawiera wiele niewiadomych, uwzględnij etap odkrywania lub badania oddzielnie od tworzenia dokumentacji.
Koordynacja i komunikacja
- Prowadź dziennik spotkań, w którym będą zapisywane podejmowane decyzje, aby ułatwić wszystkim osobom pracującym nad projektem zrozumienie kontekstu i kolejnych kroków.
- Określ, jakiego rodzaju i jak często mają być prowadzone rozmowy, czy mają to być cotygodniowe rozmowy telefoniczne, codzienne e-maile czy aktualizacje stanu na kanale czatu.
- Szybko reaguj i przekazuj jasne opinie, które zawierają uzasadnienie, a nie tylko opis problemu.
- Połącz autorów tekstów technicznych z szerszą społecznością, aby zapewnić im kontekst i umożliwić im dzielenie się swoją pracą.
Procesy i narzędzia
- Utwórz proces dokumentowania, który będzie trwał dłużej niż program Sezon na dokumenty i do którego będzie mogła się przyczynić cała społeczność.
- Sprawdzanie dokumentacji zajmie co najmniej tyle samo czasu i będzie równie intensywne jak sprawdzanie kodu. Zaplanuj na to wystarczająco dużo czasu.
Niektóre rekomendacje zostały zmienione i skrócone w celu zwiększenia przejrzystości.
Podobnie jak w programie z 2021 r., większość autorów technicznych w programie na sezon 2022 r. aplikowała bezpośrednio do organizacji, z którymi współpracowała.
Typowe problemy w pracy z autorami treści technicznych
W programie z 2022 r. odnotowano mniej problemów z współpracy z pisarzami technicznymi. Największym problemem było to, że autorzy techniczni nie mogli ukończyć programu z powodu choroby, podjęcia pracy na pełen etat lub niemożności dotrzymania terminów.
Jeden z projektów zgłosił, że jego projekt dokumentacji jest zależny od pracy wykonywanej w ramach Google Summer of Code i że tymi zależnościami trudno jest zarządzać. Inny projekt napotkał na trudności, gdy sprzęt, którego potrzebował autor tekstów technicznych, został skonfiskowany przez Ministerstwo Obrony w jego kraju i nie można było go zaimportować.
Ankiety kontrolne
W 2023 r. do uczestników badania z 2022 r. zostaną wysłane 3 ankiety kontrolne: w maju, sierpniu i listopadzie. Będziemy aktualizować tę sekcję, gdy tylko otrzymamy wyniki.
Pytania na przyszłość
Jak zawsze, im więcej dowiadujemy się o dokumentacji w open source, tym więcej chcemy się nauczyć.
W przyszłych sezonach chcemy:
- zbierać więcej metadanych projektu, aby szukać korelacji między wiekiem projektu, wielkością społeczności lub językiem a potrzebami dotyczącymi dokumentacji;
- Przeanalizuj projekty dokumentacji, aby sprawdzić, czy można je uprościć do szablonów, które można udostępniać.
- Opracowanie kryteriów oceny podczas rozmów z treściopisarzami technicznymi w projektach open source
Chociaż mamy wiele pytań, które chcielibyśmy zbadać, chcemy też uszanować czas administratorów i opiekunów projektów open source, którzy biorą udział w sezonie na dokumenty. Najważniejszym priorytetem programu jest wspieranie projektów w rozwiązywaniu problemów z dokumentacją.