Obecny etap:
Program Sezon Dokumentów 2021 zakończył się 14 grudnia 2021 r. Sprawdź oś czasu.
Sezon Dokumentów – informacje
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 2021
Zmiany w programie w 2021 roku
W latach 2019 i 2020 organizacje i twórcy treści technicznych oddzielnie zgłosili się do programu Sezon of Dokumenty, a twórcy techniczni zostali skierowani do poszczególnych organizacji przez administratorów programu Season of Dokumenty. Organizacje zapewniały mentorów do pracy z autorami tekstów technicznych, którzy otrzymywali stypendium za swoją pracę w zależności od ich lokalizacji. W ramach programu sprawdzano, czy autorzy techniczni, mentorzy i administratorzy organizacji są zadowoleni z udziału w programie, ale nie zmierzono wyników w zakresie dokumentacji.
W 2021 roku zespół Sezonu Dokumentów wprowadził istotne zmiany w programie, kładąc nacisk na pomiary wyników dokumentacji i dają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ż o dołączenie do organizacji za pośrednictwem Google, lecz bezpośrednio do zaakceptowanych organizacji.
- Wybrane organizacje otrzymywały granty przez Open Collective, a następnie wynagradzały twórców technicznych.
- Wynagrodzenie dla autorów tekstu technicznego zostało ustalone przez organizacje
- Organizacje przesłały oceny końcowe, studia przypadków i ankiety uzupełniające.
Wnioski ogólne z 2021 r.
Organizacje
- Zmiany w programie na 2021 rok sprawiły, że mniej organizacji zgłaszało się do programu (w 2021 roku odnotowaliśmy o 30% mniej organizacji niż w 2020 roku), ale administratorzy organizacji w 2021 roku byli nieco bardziej zadowoleni z programu niż administratorzy z 2020 roku (93% i 91%).
Problemy, typy dokumentów i dane
- Większość projektów koncentrowała się na tworzeniu dokumentacji w celu zmniejszenia obciążenia pracą (przez ograniczenie problemów/pytań) i/lub zwiększenie zaangażowania w projekt (przez użytkowników lub współtwórców).
- 50% zaakceptowanych organizacji utworzyło samouczki lub instrukcje.
- Ponad 50% przyjętych organizacji uznało, że ich bieżąca dokumentacja jest nieuporządkowana, nieuporządkowana lub nieaktualna.
- Zasadniczo projektom chciano mierzyć efektywność dokumentacji na podstawie interakcji, zwłaszcza przy mniejszej liczbie zgłaszanych problemów i większej liczbie osób korzystających z dokumentów i uczestnictwa w projektach.
- Dane z listopada 2022 roku odpowiadają 25 z 30 projektów:
- 18 projektów twierdzi, że osiągnęło pierwotne wskaźniki
- 5 projektów osiągnęło zmienione wskaźniki
- 2 projekty potwierdziły, że jest jeszcze za wcześnie na informacje
Udział w programie
- Najtrudniejszym częścią programu dla administratorów organizacji było rekrutowanie i zatrudnianie autorów treści technicznych oraz dokonywanie płatności za ich pracę.
- Według stanu na listopad 2022 roku 24 z 30 organizacji odpowiadały na te pytania:
- 18 organizacji nadal pracowało ze swoimi autorami technicznymi w tym sezonie (jako stale współtwórca lub źródło odpowiedzi na pytania).
- 4 organizacje pracowały ze swoim sezonem twórców technicznych w Dokumentach na płatnym stanowisku.
- 18 organizacji nadal pracowało ze swoimi autorami technicznymi w tym sezonie (jako stale współtwórca lub źródło odpowiedzi na pytania).
Najciekawsze w 2021 roku
- W przypadku wielu projektów wskazano, że ich autor techniczny zamierza kontynuować pracę nad projektem po zakończeniu programu Sezon of Dokumenty.
- Do firmy Metanorma zgłosiło się tak wielu wykwalifikowanych twórców technicznych, że znaleźli odpowiednie fundusze, aby zatrudnić dodatkowego pisarza do pracy w trakcie programu Sezon twórców Dokumentów.
- Moja Global odkryła, że społeczność jest bardzo zaangażowana w pracę nad dokumentacją i założyła nową grupę roboczą ds. dokumentacji, aby umożliwić większej liczbie osób pracę 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 zaakceptowanych. (Informacje o kryteriach wyboru znajdziesz w przewodniku Tworzenie aplikacji). Pełną listę organizacji uczestniczących w programie można znaleźć na stronie programu Dokumentów. Wszystkie 30 przyjętych organizacji przesłało ostateczny raport ze studium przypadku, aby dokończyć swój udział w programie na 2021 r.
Informacje o organizacjach
Organizacje uczestniczące w sezonie Dokumentów 2021 reprezentowały różne projekty open source. W ramach kohorty w 2021 r. znajdowały się:
- dużych projektów językowych, takich jak Julia, Perl czy R;
- Projekty z dziedziny edukacji, klimatu, technologii finansowych, opieki zdrowotnej, usługi biblioteczne, systemy uczące się, spektrometria masowa, umowy publiczne i robotyka
- projekty dla programistów, w tym narzędzia do inżynierii chaos, rozmycie, pakiety SDK czatbotów, potoki analizy kompozycji oprogramowania, narzędzia do monitorowania wydajności oraz narzędzia do programowania wizualnego;
- projekty dokumentacji dotyczącej narzędzi do dokumentacji, takich jak Redocly czy Metanorma;
Projekty ekosystemu Pythona były największą podkategorią. W kohorcie w 2021 roku uwzględniono ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite i SymPy.
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.
Problemy z dokumentacją przedstawiane przez organizacje z 2021 roku to bardzo częste problemy zarówno w projektach open source, jak i w ogólnie w dokumentacji technicznej.
Oto najważniejsze problemy, które organizacje chciał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 tworzonych dokumentów
Samouczki były najczęściej wspominanym rodzajem dokumentacji w studiach przypadków w 2021 roku.
Inne typy dokumentacji wymienione w studiach przypadków to: potoczenie Dokumentów jako kodu, 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 wspomnianych przy planowaniu rodzajów dokumentacji przy użyciu platformy 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 prośba o budżet wynosiła 10 200 zł, a mediana – 10 000 zł. Tylko trzy organizacje zgłosiły się 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 przedstawione w studiach przypadków, a dane używane do oceny sukcesu projektów dokumentacyjnych.
Najczęściej proponowane dane to:
Inne proponowane dane to: gwiazdki na GitHubie, 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 zakończeniem opracowywania projektów technicznych a przesłaniem studiów przypadków większość osób z kohorty z 2021 roku nie była w stanie zebrać wystarczającej ilości danych, aby określić, czy ich początkowe dane zostały osiągnięte.
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 technicznymi
Największa zmiana w programie Sezon Dokumenty Google w 2021 roku dotyczyła sposobu współpracy projektów z twórcami technicznymi. We wcześniejszych sezonach pisarze techniczni zgłaszali się bezpośrednio do Google, a administratorzy programu kierowali projekty i otrzymywali stałe stypendium bezpośrednio od Google.
W 2021 roku pisarze techniczni zgłaszali się bezpośrednio do projektów, a ich budżet określał budżet wynagrodzenia dla autorów tekstu z wykorzystaniem funduszu Open Collective dostępnego w sezonie Dokumentów.
Większość projektów uczestniczących w programie w 2021 roku nie miała wystarczającego doświadczenia w rekrutacji i zatrudnianiu pisarzy technicznych, a w wielu projektach ten etap procesu wymaga dodatkowego wsparcia. W odpowiedzi na te opinie zespół Sezonu Dokumentów dodał do przewodnika po programie dokumentację na potrzeby tworzenia umów z autorami technicznymi.
Rekomendacje dotyczące zatrudnienia
Poprosiliśmy twórców o rekomendowanie innych projektów, których właściciele chcą wziąć udział w tym sezonie. Najważniejsze rekomendacje dotyczące rekrutacji to:
- Udostępniaj materiały rekrutacyjne dla pisarzy technicznych, jeszcze zanim przyjmiemy Cię do programu. Poproś społeczność o polecenie potencjalnych kandydatów.
- Udostępniaj treści użytkownikom spoza kanałów projektu. Używaj języka promującego integrację społeczną i bezpośrednio zachęcaj kandydatów ze środowisk niedostatecznie reprezentowanych do przesyłania zgłoszeń.
- Dowiedz się, jakie narzędzia są niezbędne w procesie tworzenia dokumentacji, i zatrudnij redaktorów technicznych z doświadczeniem w korzystaniu z tych narzędzi.
- Wyrażaj u autora jasnych oczekiwań technicznych dotyczących dostaw i etapów milowych, kanałów komunikacji i weryfikacji, a także procesów i terminów płatności.
- Rozważ zainwestowanie w członków społeczności i pomóż im w rozwijaniu się jako pisarz techniczny. W tym celu skorzystaj z opieki mentora i coachingu w ramach programu Season of Dokumentów.
- Przygotuj więcej czasu niż się spodziewasz na wdrażanie autorów rozwiązań technicznych, odpowiadanie na pytania i wsparcie w trakcie programu, zwłaszcza jeśli twórca nie ma wcześniejszego doświadczenia w dziedzinie projektu.
- Dokumentuj swoje procesy rekrutacji, rekrutacji i wdrażania pracowników, aby wykorzystać je w przyszłych projektach.
(Uwaga: nie wszystkie projekty zostały wskazane w studiach przypadków, w których rekrutowano kandydatów na autorów tekstów technicznych).
Typowe problemy ze współpracą z twórcami technicznymi
Pisarze techniczni, którzy brali udział w kilku projektach, musieli zrezygnować z pracy z powodu pandemii COVID, innych chorób lub obowiązków rodzinnych związanych z pandemią. W niektórych projektach wystąpiły problemy z komunikacją obejmujące niezgodność strefy czasowej lub problemy z połączeniem z internetem.
W projektach stwierdzono, że lekceważą trudności związane z wdrażaniem do swoich społeczności i konfiguracją łańcucha 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 opłaty 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 przy kolejnych programach.
Ankiety dodatkowe
W ramach programu Sezon Dokumentów poprosiliśmy użytkowników o wzięcie udziału w kolejnych ankietach. W maju, sierpniu i listopadzie 2022 r. wysłaliśmy 3 ankiety.
W ramach ankiety przeprowadzonej w ramach ankiety przeprowadzonej w ramach ankiety projektowej poproszono o potwierdzenie, że ich propozycje i linki do studium przypadku były nadal aktywne. Ankieta zawierała również pytania dotyczące powodzenia projektów (określonych na podstawie wskaźników określonych w studium przypadku) oraz stałego udziału i wynagrodzenia autorów technicznych projektu:
- Czy nadal pracujesz ze specjalistą ds. technicznych w tym sezonie?
- Jeśli Twój wykonawca techniczny nadal pracuje nad Twoim projektem, czy otrzymuje wynagrodzenie w jakikolwiek sposób?
- Czy uważasz, że projekt związany z dokumentacją zakończył się sukcesem?
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 będziemy wiedzieć:
- Czy domeny projektu są skorelowane z wyborem typu dokumentu lub wyboru wskaźnika
- Które praktyki związane z zatrudnianiem i wdrażaniem pisarzy technicznych najlepiej sprawdzają się w realizacji projektów i utrzymaniu pisarzy technicznych?
- Rozsądne terminy pomiaru skuteczności dokumentacji
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.