Obecny etap:
Program Sezon Dokumentów 2021 zakończył się 14 grudnia 2021 r. Zobacz oś czasu.
Sezon Dokumentów – informacje
Seasonal of Docs to program na rzecz 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 typu open source na podstawie dokumentacji
- Zapewnij twórcom technicznym szansę na zdobycie doświadczenia w modelu open source
- zwiększenie świadomości w zakresie oprogramowania open source, dokumentacji i technik technicznych;
- Gromadzenie i udostępnianie informacji o efektywnych wskaźnikach w dokumentacji open source
Więcej informacji o sezonie Dokumentów znajdziesz na stronie programu.
Omówienie programu na rok 2021
Zmiany w programie w 2021 roku
W 2019 i 2020 roku organizacje i twórcy treści technicznych pojedynczo zgłosili się do programu Season of Docs, a twórcy treści technicznych zostali skontaktowani z organizacjami przez administratorów tego programu. Organizacje zapewniały mentorów do pracy z twórcami treści technicznych, którzy otrzymywali stypendia za swoją pracę w zależności od ich lokalizacji. W ramach programu sprawdzaliśmy, czy autorzy tekstów, mentorzy i administratorzy organizacji byli zadowoleni z udziału w programie, ale nie zmierzono wyników dokumentacji.
W 2021 roku zespół Sezon of Docs wprowadził istotne zmiany w programie, skupiając się na pomiarze wyników dokumentacji i zapewniając większą elastyczność organizacjom i twórcom treści technicznych.
- Organizacje zgłoszone z propozycjami projektu, w tym budżet i proponowane wskaźniki
- Autorzy tekstów technicznych nie ubiegają się już przez Google o dołączenie do organizacji, lecz bezpośrednio w zaakceptowanych organizacjach.
- Przyjęte organizacje otrzymywały granty w ramach Open Collective, a następnie opłacając je dla pisarzy technicznych.
- Wynagrodzenia dla autorów tekstów technicznych jest ustalane przez organizacje.
- Organizacje przesłały oceny końcowe, studia przypadków i ankiety uzupełniające
Wyniki ogólne z 2021 roku
Organizacje
- Zmiany w programie w 2021 r. spowodowały, że mniej organizacji zgłaszało się do programu (w 2021 r. było ich o 30% mniej niż w 2020 r.), ale administratorzy organizacji z 2021 roku byli nieco bardziej zadowoleni z programu niż administratorzy z 2020 roku (93% w porównaniu z 91%).
Problemy, typy dokumentów i dane
- Większość projektów koncentrowała się na tworzeniu dokumentacji mającej na celu zmniejszenie obciążenia pracą (przez zmniejszenie liczby problemów/pytań) i zwiększenie udziału w projekcie (przez użytkowników lub współtwórców).
- 50% zatwierdzonych organizacji utworzyło samouczki lub instrukcje.
- Ponad 50% zaakceptowanych organizacji uważało, że ich obecna dokumentacja jest brakująca, jest nieuporządkowana lub nieaktualna.
- Na ogół chciano mierzyć efektywność dokumentacji poprzez interakcje, zwłaszcza przy mniejszej liczbie zgłaszanych problemów, większej liczbie osób odwiedzających dokumentację i uczestnictwa w projektach.
- Według stanu na listopad 2022 roku 25 z 30 projektów odpowiada:
- 18 projektów twierdzi, że osiągnęło pierwotne wskaźniki
- 5 projektów osiągnęło poprawione wskaźniki
- 2 projekty uznały, że jest jeszcze za wcześnie na informacje
Uczestnictwo w programie
- Rekrutacja, zatrudnianie i opłacanie pracy redaktorów technicznych było najtrudniejszym elementem programu dla administratorów organizacji.
- Według stanu na listopad 2022 roku 24 z 30 organizacji odpowiadały:
- 18 organizacji nadal pracowało z twórcami materiałów technicznych Sezonu Dokumentów (jako stale współtwórca lub zasoby do odpowiadania na pytania).
- 4 organizacje pracowały na stanowisku „Sezon of Dokumentów” (w języku angielskim)
- 18 organizacji nadal pracowało z twórcami materiałów technicznych Sezonu Dokumentów (jako stale współtwórca lub zasoby do odpowiadania na pytania).
Najciekawsze momenty 2021 roku
- W przypadku wielu projektów wskazano, że ich autor techniczny zamierza kontynuować pracę nad swoim projektem po zakończeniu programu Season of Docs.
- Do zespołu Metanorma zgłosiło się tak wielu wykwalifikowanych autorów tekstu, że znajdowali odpowiednie środki na zatrudnienie dodatkowego autora do współpracy z twórcą Sezonu wspieranego przez Dokumenty w trakcie programu.
- Moja Global odkryła, że społeczność bardzo zaangażowała się w pracę nad dokumentacją i powstała nową grupę roboczą Dokumentacja robocza, aby umożliwić większej liczbie uczestników branie udziału w pracy nad dokumentacją projektu
Dane podsumowujące 2021 r.
W 2021 roku do programu zgłosiły się 82 organizacje, a 30 organizacji open source zostało przyjętych. (Informacje o kryteriach wyboru znajdziesz w przewodniku Tworzenie aplikacji). Pełną listę organizacji uczestniczących w programie znajdziesz na stronie Sezonu Dokumentów. Aby dokończyć swój udział w programie w 2021 roku, wszystkie 30 przyjętych organizacji przesłało ostateczny raport ze studium przypadku.
Informacje o organizacjach
Organizacje uczestniczące w sezonie Dokumentów 2021 reprezentowały różnorodne projekty open source. W kohorcie w 2021 r. znajdowały się:
- dużych projektów językowych, takich jak Julia, Perl i R;
- Projekty z zakresu edukacji, klimatu, technologii finansowych, opieki zdrowotnej, usług bibliotecznych, systemów uczących się, spektrometrii mas, zamówień publicznych i roboty
- Projekty dla programistów, w tym narzędzia do inżynierii chaosu, rozmycia, pakiety SDK czatbotów, potoki analizy kompozycji oprogramowania, narzędzia do monitorowania wydajności i narzędzia do programowania wizualnego
- Projekty dokumentacji narzędzi, takich jak Redocly czy Metanorma
Projekty ekosystemu Pythona były największą podkategorią. W 2021 roku w kohorcie znalazły się ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite i SymPy.
Nie zebraliśmy żadnych metadanych dotyczących projektu (takich jak data założenia, rozkład geograficzny współtwórców, liczba współtwórców czy wielkość grupy użytkowników).
Poprosiliśmy poszczególne projekty o wskazanie używanej licencji open source.
Problemy z dokumentacją omawiane przez organizacje z 2021 roku to bardzo częste problemy zarówno w projektach open source, jak i w ogólnej dokumentacji technicznej.
Oto najważniejsze problemy, które organizacje miały rozwiązać w ramach programu na 2021 rok:
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 2021, która zawiera linki do pełnych studiów przypadków dotyczących poszczególnych organizacji.
Rodzaje opracowanych dokumentów
Samouczki były najczęściej wspomnianym rodzajem dokumentacji w studiach przypadków w 2021 roku.
Inne typy dokumentacji wymienione w studiach przypadków to: Potok dokumentów jako kod, Diagram, Słowniczek, Przewodnik stylistyczny, najczęstsze pytania, Internacjonalizacja, Codelabs, Model treści, Moduły, Dokumentacja koncepcyjna, Komunikaty o błędach, Badania użytkowników, Readme, Baza wiedzy.
Niektóre z tych kategorii są przybliżone, a pojedynczy projekt dokumentacji może zawierać wiele typów dokumentacji lub funkcji.
Kilka projektów przywołanych podczas planowania dokumentacji (w języku angielskim) Diátaxis.
Więcej informacji znajdziesz na stronie wyników dotyczącej sezonu Dokumentów 2021, która zawiera linki do pełnych studiów przypadków dotyczących poszczególnych organizacji.
Budżety
W 2021 r. średnia wartość żądania budżetu wynosiła 10 200 USD, a mediana 10 000 USD. Tylko trzy organizacje zgłosiły się do wniosku i otrzymały maksymalny możliwy grant (15 tys. USD), a kolejne trzy zgłosiły wniosek o najniższy możliwy grant (5000 USD).
Dane
Projekty zostały opisane w studiach przypadków oraz dane, które posłużyły do pomiaru sukcesu projektów dokumentacyjnych.
Najczęściej proponowane dane to:
Inne proponowane wskaźniki to m.in. gwiazdki GitHub, czas spędzony na stronie, konwersje z list adresowych, jakościowe testy użytkowników, liczba uczestników forów, liczba partnerów/wolontariuszy/integracji.
Ze względu na krótki okres między opracowaniem pisania technicznego a przesłaniem studiów przypadków większość uczestników z 2021 roku nie była w stanie zgromadzić wystarczającej ilości danych, aby określić, czy udało się osiągnąć ich początkowe dane.
Więcej informacji znajdziesz na stronie wyników dotyczącej sezonu Dokumentów 2021, która zawiera linki do pełnych studiów przypadków dotyczących poszczególnych organizacji.
Współpraca z twórcami treści technicznych
Największą zmianą w programie Sezon of Dokumenty w 2021 roku była współpraca projektów z twórcami treści technicznych. We wcześniejszych sezonach pisarze ds. technicznych zgłaszali się bezpośrednio do Google, a administratorzy programu kierowali projektami i otrzymywali stały stypendium bezpośrednio od Google.
W 2021 roku pisarze techniczni zgłaszali się bezpośrednio do projektów, a w przypadku tych projektów określono budżet wynagrodzenia dla autorów tekstów technicznych z wypłatami za pomocą funduszu Open Collective (Smooth of Docs).
Większość projektów uczestniczących w programie w 2021 roku nie miała żadnego lub prawie żadnego doświadczenia w rekrutacji i zatrudnianiu pisarzy technicznych. Wiele projektów określa się jako taki, który wymaga dodatkowego wsparcia. W odpowiedzi na te opinie zespół Season of Docs dodał do przewodnika po programie dokumentację na potrzeby tworzenia umów technicznych z autorami treści.
Rekomendacje dotyczące zatrudnienia
Poprosiliśmy użytkowników o przygotowanie rekomendacji do innych projektów, które chcą wziąć udział w sezonie dokumentów. Najlepsze rekomendacje dotyczące zatrudnienia:
- Udostępniaj materiały rekrutacyjne dla pisarzy technicznych tak szybko, jak to możliwe, jeszcze zanim przyjmiemy Cię do programu. Poproś społeczność o polecenie potencjalnych kandydatów.
- Udostępniaj materiały wielu osobom poza kanałami projektu. Używaj języka promującego integrację społeczną i bezpośrednio zachęcaj do przesyłania zgłoszenia kandydatów z niedostatecznie reprezentowanych środowisk.
- Dowiedz się, jakie narzędzia są niezbędne w procesie tworzenia dokumentacji, i zatrudnij redaktorów technicznych, którzy mają doświadczenie w ich korzystaniu.
- Jasno określ oczekiwania wobec autora tekstu technicznego w kwestiach dotyczących dostaw i etapów, kanałów komunikacji i weryfikacji, procesów i terminów płatności.
- Pomyśl o zainwestowaniu w członków społeczności i pomóż im rozwijać się w zakresie pisania tekstów technicznych. W tym celu skorzystaj z pomocy mentora i coachingu za pomocą Sezonu Pisarzy technicznych.
- Budżet na wprowadzanie redaktorów technicznych, odpowiadanie na pytania i udzielanie pomocy w trakcie programu może zająć więcej czasu niż się spodziewasz, zwłaszcza jeśli autor tekstu nie ma wcześniejszego doświadczenia w dziedzinie Twojego projektu.
- Dokumentuj swój proces rekrutacji, zatrudnienia i wdrażania, aby wykorzystać je w kolejnych projektach.
(Uwaga: nie wszystkie projekty ujęte w studiach przypadków, w których rekrutowano kandydatów pisarzy technicznych).
Typowe problemy ze współpracą z twórcami treści technicznych
Autorzy kilku projektów musieli zrezygnować z pracy z powodu pandemii COVID lub innych chorób albo obowiązków rodzinnych związanych z pandemią. W niektórych projektach zgłoszono problemy z komunikacją, w tym niezgodność strefy czasowej lub problemy z połączeniem internetowym.
Projekty pokazały, że nie doceniają oni trudności związanych z wdrażaniem się do społeczności czy tworzeniem łańcucha narzędzi dokumentów.
W przypadku niektórych projektów płatności były opóźnione ze względu na problemy bankowe z Open Collective lub z powodu ograniczeń płatności w krajach, w których mieszkają autorzy.
Dokumentacja programu dotycząca opłat Open Collective była niezrozumiała: firma Google pokryła opłaty transakcyjne Open Collective za początkowy transfer środków do projektów, ale nie za transakcje nałożone przez inne kanały płatności (np. opłaty za wymianę walut). Postaramy się to wyjaśnić w dokumentacji przyszłych programów.
Ankiety dodatkowe
W ramach programu Sezon Dokumentów poproszono projekty o wzięcie udziału w kolejnych ankietach. W maju, sierpniu i listopadzie 2022 r. wysłaliśmy 3 ankiety.
W kolejnej ankiecie poprosiliśmy o potwierdzenie, że linki do propozycji i studium przypadku są nadal aktywne. Ankieta zawierała również pytania dotyczące sukcesu ich projektów (określanych na podstawie wskaźników określonych w studium przypadku) oraz stałego uczestnictwa i wynagrodzenia autorów projektów technicznych:
- Czy nadal pracujesz ze specjalistą ds. technicznych w tym sezonie?
- Jeśli Twój dziennikarz techniczny nadal pracuje nad Twoim projektem, czy otrzymujesz mu jakieś wynagrodzenie?
- Czy uważasz, że projekt związany z dokumentacją zakończył się sukcesem?
Przyszłe pytania
Jak zawsze – im więcej dowiadujemy się o dokumentacji w modelu open source, tym więcej chcemy się dowiedzieć. Mamy nadzieję, że w kolejnych sezonach poznasz:
- Określa, czy domeny projektów są skorelowane z wyborem typu dokumentu lub wskaźnika
- Które metody zatrudniania i wdrażania pisarzy technicznych są najskuteczniejsze w zakresie realizacji projektów i utrzymywania pisarzy technicznych
- Rozsądne terminy pomiaru skuteczności dokumentacji
Chociaż chcielibyśmy odpowiedzieć na wiele pytań, chcemy szanować czas administratorów projektu open source i opiekunów, którzy biorą udział w tym programie. Priorytetem programu jest wspieranie projektów w rozwiązywaniu problemów z wykorzystaniem dokumentacji.