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 Sezonie dokumentów znajdziesz na stronie programu.
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 zawiera:
- 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 są przejrzyste. Budżety są zawarte 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 autorzy prowadzą teraz grupy robocze i spotkania 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 systemem operacyjnym OpenMined i mamy z nimi bardzo dobre doświadczenia”. – OpenMined
„Ponadto nowy podręcznik jest znacznie prostszy dla początkujących użytkowników obliczeniowej 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-tygodniową 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 technicznych wyraziło zainteresowanie udziałem w programie, dodając swoje dane kontaktowe i linki do swoich portfolio w repozytorium GitHub Season of Docs.
W programie z 2022 roku:
- 100% organizacji pozytywnie oceniło proces rejestracji
- 100% organizacji pozytywnie oceniło dokumentację/treści na stronie programu
- 93% organizacji pozytywnie oceniło udział w programie
- 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, geograficzna dystrybucja 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ć za pomocą 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 lub 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 je otrzymało. Trzy organizacje poprosiły o najniższy grant (5–7 tys. USD) i je otrzymały.
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ększona świadomość 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 grupy z 2022 r. nie była w stanie zebrać wystarczającej ilości danych w momencie przesyłania tych 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
Projekty zostały poproszone o udostępnienie sprawdzonych metod rekrutacji, zatrudniania i współpracy z pisarzami technicznymi. Najlepsze rekomendacje to:
Rekrutacja
- Zamiast przeglądać tylko CV, przeprowadź rozmowy kwalifikacyjne 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ć dodatkowych wysiłków, aby utrzymać dobrą komunikację.
Zatrudniamy
- Użyj umowy, która jasno określa zobowiązania, harmonogramy płatności i terminy.
- 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 masz kontaktować się z użytkownikiem, np. 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 Season of Docs 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. wysłała zgłoszenie bezpośrednio do organizacji, z którą współpracowała.
Typowe problemy w pracy z autorami treści technicznych
W programie z 2022 r. odnotowano mniej problemów z współpracownią 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 wiemy 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;
- przeanalizować projekty dokumentacji, aby sprawdzić, czy można je uprościć do postaci szablonów do udostępniania;
- Opracowanie kryteriów oceny podczas przeprowadzania rozmów kwalifikacyjnych z tłumaczami 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 Docs. Najważniejszym priorytetem programu jest wspieranie projektów w rozwiązywaniu problemów z dokumentacją.