Raport ze studium przypadku z 2021 r.

Informacje o Season of Docs

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 rozwiązywaniu problemów z dokumentacją,
  • 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 2021

Zmiany w programie w 2021 r.

W latach 2019 i 2020 organizacje i treści techniczne były rejestrowane w programie Sezon na dokumenty osobno, a treści techniczne były dopasowywane do organizacji przez administratorów programu. Organizacje zapewniły mentorów, którzy współpracowali z tłumaczami technicznymi. Ci ostatni otrzymali stypendium za swoją pracę w zależności od lokalizacji. W ramach programu sprawdzano, czy autorzy techniczni, mentorzy i administratorzy organizacji są zadowoleni z uczestnictwa w programie, ale nie sprawdzano wyników związanych z dokumentacją.

W 2021 r. zespół programu Season of Docs wprowadził w nim istotne zmiany, przenosząc nacisk na pomiar wyników związanych z dokumentacją i umożliwiając większą elastyczność organizacjom i pisarzom technicznym.

  • Organizacje, które przesłały propozycje projektów, w tym budżet i proponowane dane
  • Specjaliści ds. pisania technicznego nie są już dołączani do organizacji przez Google, ale bezpośrednio do organizacji, które zostały zaakceptowane.
  • Zaakceptowane organizacje otrzymały dotacje za pośrednictwem Open Collective, które wykorzystały do opłacania copywriterów
  • Wynagrodzenie dla autorów technicznych zostało ustalone przez organizacje
  • Organizacje przesłały ostateczne oceny i studia przypadków oraz odpowiedziały na ankiety uzupełniające.

Ogólne wyniki z 2021 r.

Organizacje

  • Zmiany w programie w 2021 r. spowodowały, że zgłosiło się mniej organizacji (w 2021 r. było ich o 30% mniej niż w 2020 r.), ale administratorzy organizacji w 2021 r. byli nieco bardziej zadowoleni z programu niż w 2020 r. (93% w porównaniu z 91%).

Problemy, typy dokumentów i wskaźniki

  • Większość projektów skupiała się na tworzeniu dokumentacji, aby zmniejszyć obciążenie konserwatora (poprzez zmniejszenie liczby problemów i pytań) lub zwiększyć udział w projekcie (użytkowników lub współtwórców).
    • 50% zaakceptowanych organizacji utworzyło samouczek lub instrukcję.
    • Ponad 50% zaakceptowanych organizacji uznało, że ich obecna dokumentacja jest niekompletna, nieuporządkowana lub nieaktualna.
  • Projekty zazwyczaj chciały mierzyć skuteczność dokumentacji na podstawie interakcji, zwłaszcza mniejszej liczby zgłoszonych problemów i większej liczby odwiedzających dokumenty oraz uczestniczących w projektach.
  • Według stanu na listopad 2022 r. 25 z 30 projektów, które odpowiedziały na ankietę:
    • 18 projektów osiągnęło pierwotne wskaźniki
    • 5 projektów spełniało zaktualizowane kryteria
    • 2 projekty – według ich autorów jest jeszcze za wcześnie, aby to ocenić

Udział w programie

  • Najtrudniejszym zadaniem dla administratorów organizacji było rekrutowanie, zatrudnianie i wypłacanie wynagrodzenia autorom dokumentacji technicznej.
  • W listopadzie 2022 r. 24 z 30 organizacji, które odpowiedziały na ankietę, podały następujące informacje:
    • 18 organizacji nadal współpracowało ze swoimi autorami technicznymi z cyklu „Sezon na dokumenty” (jako stały autor lub osoba udzielająca odpowiedzi na pytania).
      • 4 organizacje współpracowały z płatnymi autorami technicznymi w ramach programu Season of Docs

Najciekawsze momenty z 2021 r.

  • W przypadku wielu projektów autorzy techniczni wskazali, że zamierzają kontynuować pracę nad projektem po zakończeniu programu Sezon na dokumenty
  • Metanorma otrzymała tak wiele zgłoszeń od wykwalifikowanych autorów technicznych, że znalazła środki na zatrudnienie dodatkowego autora, który będzie współpracować z autorem wspieranym w ramach programu Docs Season.
  • Moja Global zauważyła, że społeczność jest bardzo zaangażowana w dokumentację, i utworzyła nową grupę roboczą ds. dokumentacji, aby umożliwić większej liczbie autorów udział w dokumentacji projektu.

Dane zbiorcze z 2021 r.

W 2021 r. zgłosiło się 82 organizacje, a 30 z nich zostało zakwalifikowanych do udziału w programie. (kryteria wyboru znajdziesz w przewodniku Tworzenie aplikacji). Pełną listę organizacji uczestniczących w akcji znajdziesz na stronie Season of Docs. Wszystkie 30 zakwalifikowanych organizacji przesłało raport z ostatniego studium przypadku, aby zakończyć udział w programie w 2021 r.

Organizacje

Organizacje biorące udział w sezonie Dokumenty 2021 reprezentowały różnorodną gamę projektów open source. Grupa z 2021 r. obejmowała:

  • duże projekty dotyczące języków, takie jak Julia, Perl i R;
  • projekty z zakresu edukacji, klimatu, fintechu, opieki zdrowotnej, usług bibliotecznych, uczenia maszynowego, spektrometrii masowej, umów publicznych i robotyki;
  • projekty skierowane do programistów, w tym narzędzia do testowania odporności na awarie, fuzzery, pakiety SDK do tworzenia chatbotów, oprogramowanie do analizy składu oprogramowania, narzędzia do monitorowania wydajności i narzędzie do programowania wizualnego;
  • projekty dotyczące narzędzi do tworzenia dokumentacji, takich jak Redocly i Metanorma;

Największą podkategorią były projekty w ekosystemie Pythona. W 2021 r. były to: ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite i SymPy.

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ą.

Wykres słupkowy pokazujący liczbę projektów korzystających z każdej licencji OSS: Apache 2.0: 10 programów; BSD z 3 klauzulami: 5 programów; MIT: 5 programów; GPL 2.0: 4 programy; LGPL 2.1: 4 programy; licencja publiczna Mozilla 2.0: 3 programy; Artistic, Boost i BSD z 2 klauzulami: po 1 programie

Problemy z dokumentacją wskazane przez organizacje w 2021 r. są bardzo częste zarówno w projektach open source, jak i w dokumentacji technicznej ogólnie.

Najważniejsze problemy, które organizacje chciały rozwiązać w ramach programu w 2021 r., to:

Wykres słupkowy pokazujący problemy zgłoszone przez organizacje: brak dokumentacji dla konkretnych przypadków użycia aspektów projektu (14 projektów); dokumentacja jest nieuporządkowana (14 projektów); dokumentacja jest nieaktualna (6 projektów); dokumentacja jest niespójna (3 projekty); dokumentację trzeba przekształcić w inne narzędzie, platformę lub format (2 projekty)

Pamiętaj, że organizacje mogą zgłaszać wiele problemów z dokumentacją. Więcej informacji znajdziesz na stronie z wynikami konkursu Docs Season 2021, na której znajdziesz linki do pełnych historii klientów.

Typy tworzonej dokumentacji

W studiach przypadków z 2021 r. najczęściej wspominano samouczki.

Wykres słupkowy przedstawiający typy utworzonej dokumentacji: samouczki: 9 projektów; instrukcje: 6 projektów; wprowadzenie: 3 projekty; przykłady: 3 projekty; odniesienia: 3 projekty; dokumenty API, filmy, przewodniki uruchamiania, szablony, strony docelowe: po 2 projekty każdy

Inne typy dokumentacji wymienione w przypadkach zastosowań to przepływ danych w Dokumentach jako kodzie, diagram, glosariusz, przewodnik po stylu, najczęstsze pytania, międzynarodowość, Codelab, model treści, moduły, dokumentacja koncepcji, komunikaty o błędach, badania użytkowników, Readme, baza wiedzy.

Niektóre z tych kategorii są nieostre, a jeden projekt dokumentacji może zawierać wiele typów lub funkcji dokumentacji.

Kilka projektów, które korzystają z ram Diátaxis jako przewodnika po planowaniu typów dokumentacji.

Więcej informacji znajdziesz na stronie z wynikami konkursu Docs Season 2021, na której znajdziesz linki do pełnych historii klientów.

Budżety

W 2021 r. średnia prośba o budżet wynosiła 10 200 USD, a mediana – 10 tys. USD. Tylko 3 organizacje poprosiły o maksymalny grant (15 tys. USD) i tylko 3 o najniższy (5 tys. USD).

Dane

W projektach opisanych w ich studiach przypadków podano dane, których używali do oceny skuteczności projektów dokumentacji.

Najczęściej proponowane dane to:

Wykres słupkowy przedstawiający wskaźniki skuteczności dokumentacji: mniej problemów/pytań dotyczących projektu (13 projektów); więcej użytkowników dokumentacji/wykorzystujących dokumenty (9 projektów); więcej autorów/żądań pull (8 projektów); więcej żądań pull/wkładów w dokumentację (7 projektów); łączna liczba utworzonych dokumentów (5 projektów); większa satysfakcja z dokumentacji (na podstawie ankiety), częstsze korzystanie z projektu, więcej bezpośrednich opinii na stronach dokumentacji (po 4 projekty każdy); lepszy SEO (3 projekty); łączny odsetek przekształconej dokumentacji i łączny odsetek informacji docelowych objętych dokumentacją (po 2 projekty każdy).

Inne proponowane wskaźniki to gwiazdki GitHub, czas spędzony na stronie, konwersje na liście mailingowej, jakościowe testy użytkowników, liczba uczestników na forach, liczba partnerów/wolontariuszy/integracji.

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ść osób z grupy z 2021 r. nie była w stanie zebrać wystarczającej ilości danych, aby ustalić, czy udało im się osiągnąć początkowe wskaźniki.

Więcej informacji znajdziesz na stronie z wynikami konkursu Docs Season 2021, na której znajdziesz linki do pełnych historii klientów.

Współpraca z pisarzami technicznymi

Największa zmiana w programie Sezon na dokumenty w 2021 r. dotyczyła sposobu współpracy projektów z zespołem autorów technicznych. W poprzednich edycjach programistki/programiści specjaliści ds. treści technicznych aplikowali bezpośrednio do Google, a administratorzy programu przydzielali im projekty. Otrzymywali oni też stałą stawkę bezpośrednio od Google.

W 2021 r. specjaliści ds. dokumentacji aplikowali bezpośrednio do projektów, które ustaliły budżet na wynagrodzenie dla specjalistów ds. dokumentacji. Płatności były dokonywane za pomocą funduszu Open Collective.

Większość projektów biorących udział w programie w 2021 r. miała niewielkie lub żadne doświadczenie w rekrutowaniu lub zatrudnianiu autorów tekstów technicznych. W wielu projektach ta część procesu została wskazana jako wymagająca większego wsparcia. W odpowiedzi na tę opinię zespół programu Season of Docs dodał do przewodnika programu dokumentację dotyczącą tworzenia umów dla pisarzy technicznych.

Rekomendacje dotyczące zatrudnienia

Projekty zostały poproszone o rekomendacje dla innych projektów zainteresowanych udziałem w sezonie Dokumentów. Najważniejsze rekomendacje dotyczące zatrudniania to:

  • Udostępniaj materiały rekrutacyjne dla copywriterów technicznych jak najwcześniej, nawet zanim zostaniesz zaakceptowany do programu. Poproś społeczność o polecenie potencjalnych kandydatów.
  • Udostępnianie poza kanałami projektu. Posługiwać się językiem promującym integrację społeczną i bezpośrednio zachęcać do aplikowania kandydatów z grup niedostatecznie reprezentowanych.
  • Dowiedz się, jakie narzędzia są niezbędne do tworzenia dokumentacji, i zatrudnij autorów technicznych, którzy mają doświadczenie w korzystaniu z tych narzędzi.
  • Określ jasno oczekiwania wobec autora treści technicznych dotyczące elementów i kamieni milowych, kanałów komunikacji i spotkań kontrolnych oraz procesów i terminów płatności.
  • Zastanów się, czy warto zainwestować w członków społeczności i pomóc im w rozwoju jako autorom dokumentacji technicznej, korzystając z pomocy mentora i trenera w ramach programu Season of Docs.
  • Zaplanuj więcej czasu na wdrożenie autorów tekstów technicznych oraz udzielanie odpowiedzi na pytania i zapewnienie pomocy podczas programu, zwłaszcza jeśli autor tekstów technicznych nie ma wcześniejszego doświadczenia w dziedzinie projektu.
  • Udokumentuj proces rekrutacji, zatrudniania i wprowadzania nowych pracowników, aby wykorzystać go w przyszłych projektach.

Wykres słupkowy pokazujący źródło kandydatów na stanowisko specjalisty ds. pisania technicznego: 7 osób, które bezpośrednio zgłosiły się do programu; 4 osoby, które uczestniczyły w poprzedniej edycji SoD lub były członkami społeczności SoD na GitHubie; 3 osoby, które zgłosiły się za pośrednictwem witryny z ofertami pracy (Upwork, LinkedIn) lub były uczestniczkami Google Summer of Code lub Code-In; 2 osoby, które zgłosiły się za pośrednictwem witryny z ofertami pracy (Upwork, LinkedIn) lub były uczestniczkami Google Summer of Code lub Code-In

(Uwaga: nie wszystkie projekty wskazane w przypadkach zastosowań dotyczyły rekrutacji kandydatów na stanowisko copywritera technicznego).

Typowe problemy w pracy z autorami treści technicznych

Wykres słupkowy pokazujący problemy związane z twórcą treści technicznych: rezygnacja z TW: 8 projektów; problemy z komunikacją: 6 projektów; szkolenie TW: 4 projekty; rekrutacja TW; zatrudnianie lub wypłata; konfiguracja narzędzi projektowych: po 3 projekty w każdym przypadku

Autorzy techniczni w kilku projektach musieli zrezygnować z pracy z powodu COVID-19 lub innych chorób albo obowiązków rodzinnych związanych z pandemią. Niektóre projekty zgłaszały problemy z komunikacją związane z niezgodnością stref czasowych lub problemami z połączeniem internetowym.

Okazało się, że projektanci nie doceniali trudności związanych z włączaniem się w działanie społeczności lub konfigurowaniem narzędzia do tworzenia dokumentów.

W przypadku niektórych projektów opóźnienia w wypłacaniu wynagrodzenia autorom technicznym wynikały z problemów z bankowością w Open Collective lub z ograniczeń płatności w krajach, w których mieszkają.

Dokumentacja programu dotycząca opłat Open Collective była niejasna: Google pokrywało opłaty transakcyjne Open Collective za początkowy przelew środków na projekty, ale nie opłaty transakcyjne nałożone przez inne kanały płatności (takie jak opłaty za przeliczanie walut). Postaramy się, aby ta informacja była bardziej czytelna w dokumentacji przyszłych programów.

Ankiety kontrolne

W ramach programu Sezon Dokumentów uczestnicy zostali poproszeni o udział w ankietach podsumowujących. W maju, sierpniu i listopadzie 2022 r. wysłaliśmy 3 ankiety.

Wykres słupkowy przedstawiający liczbę odpowiedzi na ankietę kontrolną: ankieta z maja – 13 odpowiedzi; ankieta z sierpnia – 21 odpowiedzi; ankieta z listopada – 12 odpowiedzi

W ankiecie uzupełniającej poprosiliśmy projekty o potwierdzenie, że linki do ich propozycji i badań przypadkowych są nadal aktywne. Ankieta zawierała też pytania o sukces projektów (określany na podstawie danych określonych w przypadku analizowanym w badaniu) oraz o dalsze uczestnictwo i wynagrodzenie autorów dokumentacji technicznej projektu:

  1. Czy nadal współpracujesz z autorem technicznym w ramach programu Docs Season?

Wykres słupkowy przedstawiający bieżący udział autorów tekstów technicznych według ankiety: w maju 6 projektów miało autorów tekstów technicznych, którzy uczestniczyli w badaniu lub odpowiadali na pytania; 1 projekt nie miał autorów tekstów technicznych. W sierpniu 11 projektów miało udział stałego copywritera, 7 projektów nie miało stałego copywritera, a 3 projekty miały copywriterów odpowiadających na pytania. W listopadzie 5 projektów zgłosiło, że nadal korzystają z usług technicznego pisarza; 3 projekty nie korzystały z usług technicznego pisarza; a 4 projekty zgłosiły, że techniczny pisarz odpowiada na pytania.

  1. Czy Twój copywriter techniczny nadal pracuje nad projektem i czy otrzymuje za to wynagrodzenie?

Wykres słupkowy pokazujący liczbę projektów, w których przypadku w każdym z badań podano wynagrodzenie dla pisarzy technicznych. W maju 5 projektów zgłosiło, że ich copywriterzy techniczni otrzymują wynagrodzenie za bieżącą pracę, a 4 projekty zgłosiły, że ich copywriterzy techniczni nie otrzymują wynagrodzenia. W sierpniu 4 projekty zgłosiły, że płacą swojemu autorowi technicznemu, a 7 projektów zgłosiło, że nie płaci. W listopadzie 2 projekty zgłosiły, że płacą swojemu copywriterowi, a 5 projektów – że nie płacą.

  1. Czy uważasz, że Twój projekt dokumentacji zakończył się sukcesem?

Wykres słupkowy pokazujący liczbę projektów, które odnotowały sukces w porównaniu z danymi w każdym teście. W maju 6 projektów zgłosiło, że ich wskaźniki zostały osiągnięte; 6 projektów stwierdziło, że jest za wcześnie, aby to stwierdzić, a 2 projekty osiągnęły skorygowane wskaźniki. W sierpniu 16 projektów zgłosiło, że wskaźniki zostały osiągnięte, 3 projekty zgłosiły, że osiągnięto skorygowane wskaźniki, a 2 projekty zgłosiły, że jest za wcześnie, aby to stwierdzić. W listopadzie 9 projektów zgłosiło, że spełniły się wskaźniki; 3 projekty zgłosiły, że spełniły się skorygowane wskaźniki, a żaden projekt nie zgłosił, że jest jeszcze za wcześnie, aby to stwierdzić.

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 się dowiedzieć:

  • Czy domeny projektów są skorelowane z wyborem typu dokumentu lub danych
  • Które metody rekrutacji i wdrożenia autorów tekstów technicznych są najbardziej skuteczne w zakresie realizacji projektów i zatrzymywania tych pracowników
  • rozsądne terminy pomiaru skuteczności dokumentacji;

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ą.