Projekt Wikimedia Foundation

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:
The Wikimedia Foundation
Pisarz techniczny:
Pavithra Eswaramoorthy
Nazwa projektu:
Ulepszenie dokumentacji dla dokumentalistów technicznych i operatorów filmowych Wikimedia
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

1. O mnie

Kilka miesięcy temu zetknęłam się z oprogramowaniem typu open source i prawie od razu poczułam się przytłoczona jego nieograniczonym zakresem. Podczas próby przebrnięcia przez miliardy projektów dowiedziałem się o inicjatywach open source, takich jak Google Summer of Code i Outreachy. Sezon Dokumentów Google wydawał się interesujący, a pomysły na projekty Fundacji Wikimedia wzbudziły moją ciekawość, więc zaczęłam się bardziej interesować tą inicjatywą.

Moja dotychczasowa podróż była równie ekscytująca, co skomplikowana, pełna pytań „Co?!”, „Aha!” i „Czy mam to skomentować?”. Społeczność Wikimedia wspierała mnie na każdym kroku. Od edycji stron po tworzenie rozszerzeń – codziennie uczę się czegoś nowego.

Zgodnie z oczekiwaniami proces zgłaszania posłużył mi jako brama do społeczności open source. Inspiracją dla tej propozycji były moje własne doświadczenia jako początkujące.

2. Projekt

2.1. Kontur

Celem tego projektu jest ulepszenie dokumentacji dla autorów tekstów technicznych i potencjalnych operatorów kamery w Wikimedii. Dopracowany zestaw wytycznych dotyczących dokumentacji technicznej pomoże ulepszyć ogólną dokumentację, a odwołania do tworzenia screencastów umożliwiłyby skuteczną prezentację funkcji oprogramowania. Istniejąca dokumentacja dotycząca tych obszarów może zostać rozszerzona, aby lepiej wspierać zarówno nowych, jak i doświadczonych współtwórców. Aby rozwinąć tę sieć poręcznych zasobów, zostanie przyjęte podejście stopniowe.

2.2. Dostarczane materiały

  • T197006 [https://phabricator.wikimedia.org/T197006] – Ulepszenie dokumentacji dla dokumentalistów Wikimedia:

    • Dodaj wskazówki i przykłady do dokumentacji lub przewodnika po stylu. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Dodaj informacje specyficzne dla MediaWiki do określonych gatunków w szablonach i sugestiach dotyczących dokumentacji technicznej: przewodniki użytkownika, instrukcje, krótkie przewodniki, informacje o wersji i README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Testowanie i ulepszanie wytycznych dotyczących ustalania priorytetów w dokumentacji technicznej. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • opracować strategię gromadzenia treści dla różnych rodzajów dokumentacji;
    • Opracowanie strategii komunikacji i współpracy w zakresie dokumentacji MediaWiki.
    • Utwórz listę kontrolną, na podstawie której autorzy będą mogli sprawdzać swoje dokumenty przed opublikowaniem.
    • rozszerzenie struktury dokumentacji dla nowych autorów technicznych, [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Wybierz listę zadań związanych z dokumentacją techniczną, które są odpowiednie do hackathonów. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Utwórz centrum dla autorów technicznych, które zawiera linki do przydatnych zasobów.

  • Ulepszona dokumentacja dla operatorów kamery w MediaWiki:

    • Utwórz krótki przewodnik po tworzeniu ogólnego screencasta.
    • Projektowanie szablonów screencastów dla MediaWiki na potrzeby samouczków i przewodników.

  • T214522 [https://phabricator.wikimedia.org/T214522] – Utwórz screencast „Wprowadzenie do Phabricator”.

2.3. Cel dodatkowy

  • Ponownie sprawdź zawartość i zaktualizuj dokumentację WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentorzy

Zulip będzie głównym sposobem komunikacji z moimi mentorami. Do dyskusji ze społecznością będą służyć kanały IRC i e-maile Wikimedia. Dyskusje na temat konkretnych zadań będą się odbywać w sekcji komentarzy do zadań w Phabricatorze.

4. Dyskusja

Ten projekt jest ogólnie podzielony na 2 fazy:

(i) ulepszać istniejące zasoby dla autorów technicznych Wikimedia;

(ii) tworzyć przydatne szablony dla potencjalnych operatorów kamery;

(i) Ulepszyć istniejące zasoby dla autorów technicznych Wikimedia.

W przeszłości podejmowano różne inicjatywy mające na celu ulepszenie dokumentacji MediaWiki, z różnym skutkiem. Oto kilka przykładów:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Dzięki tym działaniom wiemy, że lepszy zestaw zasobów dla autorów tekstów technicznych będzie miał bezpośredni wpływ na tworzone przez nich dokumenty.

Oto fragment cotygodniowego raportu stażysty w Outreachy w 2018 r., Anny e Só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

„Przewodnik po stylu MediaWiki nie jest w cale idealny, zwłaszcza że zbytnio opiera się na zewnętrznych odniesieniach, nie wskazując, które praktyki są najlepsze. Niestety ten problem nie dotyczy tylko MediaWiki, ponieważ pojawia się w innej dokumentacji, np. w artykule o najlepszych praktykach dotyczących tłumaczenia. Pisarze nie mają dobrych i rzetelnych zasobów do pracy, co utrudnia im określenie odbiorców docelowych i odpowiedniego stylu pisania. Użytkownicy, zwłaszcza nowi, mogą mieć problemy ze zrozumieniem nowych pojęć i procesów”.

T197006 [https://phabricator.wikimedia.org/T197006] opisuje też pewne obszary dokumentacji technicznej, które wymagają poprawy. Najlepszym miejscem na rozpoczęcie jest sekcja Documentation/Style_guide.

Gdy już będziemy mieć lepszy przewodnik, planujemy opublikować kolejny zestaw dokumentów, który pomoże autorom tekstów technicznych w przechodzeniu przez różne etapy pisania. Dokumentacja musi być przystępna dla początkujących, a zarazem zawierać wszystkie niezbędne informacje, do których autorzy będą mogli wrócić.

Etap przygotowania jest prawdopodobnie najważniejszy, ponieważ stanowi podstawę, na której opiera się dokument. Aby pomóc twórcom technicznym na tym etapie, przygotowaliśmy dokumenty referencyjne opisujące skuteczne sposoby gromadzenia istotnych informacji i wskazówek dotyczących porządkowania tych informacji za pomocą szablonów.

Potem następuje etap pisania. Pisarze otrzymują przykłady dobrej pracy, aby automatycznie podnieść poprzeczkę. Ponadto tworzona jest lista kontrolna z zestawem podstawowych kryteriów, którym musi odpowiadać każdy dokument. Pomoże to autorom w sprawdzaniu dokumentów przed ich opublikowaniem.

Nawet z tymi dokumentami nowi autorzy techniczni będą potrzebować dodatkowej pomocy, którą im zapewnimy. Ulepszyliśmy przewodnik dla nowych autorów tekstów technicznych i utworzyliśmy listę zadań odpowiednich do hackathonów, pogrupowanych według poziomu trudności.

Na koniec testujemy i ulepszamy dokument „Priorytetyzacja dokumentacji technicznej”, który pomaga zrozumieć proces zarządzania i utrzymywania dokumentacji.

Na koniec tej fazy zostanie utworzony dział z przewodnikami, zasobami, przykładami, sugestiami i szablonami dotyczącymi pisania tekstów technicznych, który będzie wspierać przewodnik po stylu dokumentacji.

(ii) tworzyć przydatne szablony dla potencjalnych operatorów kamery;

„Jednym z najtrudniejszych sposobów na naukę wszystkiego, co obejmuje grafikę, jest czytanie zwykłego tekstu. Wyobraź sobie też, co się stanie, jeśli Twój podręcznik odnosi się do nieprawidłowej wersji oprogramowania. W przypadku podręczników zawierających tylko tekst często niemożliwe jest odtworzenie sekwencji czynności, gdy menu i sformułowania w aplikacji ulegają zmianie, ponieważ brakuje nam wszystkich wskazówek, których zwykle używamy.

Najlepszym sposobem nauki jest prawdopodobnie siedzenie obok eksperta. Filmy z ekranu to coś pośredniego między grafiką statyczną a kontaktem z ekspertem. Mamy wizualne, ruchome demo z przyjaznym głosem. Możemy też mieć adnotacje tekstowe na ekranie i animacje. Zaletą screencastów w porównaniu z ekspertem jest to, że można je odtwarzać w dowolnej chwili w dowolnym dniu.

Możemy też dodać przetłumaczone napisy do screencasta, żeby były oglądane przez osoby, które nie są rodzimymi użytkownikami, lub zastąpić ścieżkę audio alternatywnymi językami.

W powyższym fragmencie książki „The Screencasting Handbook” [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] Ian Ozsvald wyjaśnia znaczenie screencastów. Mogą się one przydać zwłaszcza w przypadku samouczków dotyczących konfigurowania środowiska programistycznego MediaWiki, pisania rozszerzeń, korzystania z Gerrita i innych tematów.

Podobnie jak w przypadku szablonów dokumentów, posiadanie standardowego szablonu screencastów sprzyja spójności, co poprawia wrażenia widzów. Znajdziesz w nim też informacje dla potencjalnych filmowców, jak rozpocząć pracę. Dlatego opracowaliśmy krótki przewodnik dla użytkowników oraz szablony do tworzenia filmów wprowadzających i samouczków. Dokumenty zawierają wskazówki dotyczące głębokości omawianych zagadnień oraz kilka pomysłów na screencasty dla MediaWiki.

Najlepszym sposobem na przetestowanie tego szablonu i przygotowanie się do osiągnięcia celu dodatkowego jest utworzenie screencastu za pomocą narzędzi i szablonów. Dlatego powstał film „Introduction to Phabricator” („Wprowadzenie do Phabricatora”), który zawiera podstawy korzystania z tej aplikacji. W ramach tego procesu zostaną też wskazane obszary, które wymagają omówienia.

Sprawdzamy też i aktualizujemy główny materiał informacyjny dla filmowców Wikimedia – WikiProject Screencast.

5. Wstępny harmonogram

Okres nawiązywania więzi (1 sierpnia–1 września)

  • szczegółowo analizować projekt z mentorami;

  • Dyskusja na temat:

    • jak często należy sprawdzać zadania.
    • Udostępniaj harmonogramy i ustalaj przepływ pracy na tydzień lub dzień.
    • narzędzia i zasoby, których możesz użyć;
    • co 2 tygodnie i codziennie raporty projektów;

  • Utwórz wymagane zadania i podzadania w Phabricatorze.

  • Twórz wersje robocze, aby zrekompensować osobiste zobowiązania podczas fazy tworzenia dokumentu.

Tydzień 1 (2–8 września)

  • Ulepszenie dokumentacji/Style_guide:

    • Skup się głównie na sprawdzonych metodach i standardach MediaWiki.
    • Uwzględniaj przykłady dobrych prac i zwiększ widoczność powiązanych stron.

  • Ulepsz przewodnik dla początkujących twórców treści technicznych:

    • rozszerzyć strukturę dokumentacji;

Tydzień 2 (9–15 września)

  • Praca nad ustalaniem priorytetów w dokumentacji technicznej:

    • Oceń tablicę pracy dotyczącą dokumentacji. Znajdź przykłady dobrych opisów zadań i ustalania priorytetów.
    • Przeanalizuj trendy i zapisz typowe trudności.
    • Użyj informacji i przykładów, aby udokumentować standardy ustalania priorytetów.

Tydzień 3 (16–22 września)

  • Utwórz dla autorów dokumentacji technicznej następującą dodatkową dokumentację:

    • Lista kontrolna, która pomoże Ci sprawdzić dokumentację techniczną przed opublikowaniem.
    • Sposoby skutecznego zbierania treści do różnych rodzajów dokumentacji.

Tydzień 4 (23–29 września)

  • Dodaj informacje o pisaniu w najpopularniejszych gatunkach MediaWiki do szablonów i sugestii dokumentacji technicznej:

    • Zachowaj w MediaWiki sprawdzone metody tworzenia przewodników użytkownika, krótkich przewodników, plików README, informacji o wersjach i instrukcji.

  • Dodaj wskazówki, aby zwiększyć dojrzałość komunikacji technicznej. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Tydzień 5 (30 września–6 października)

  • Ulepszona dokumentacja dotycząca dodawania nowych współpracowników:

    • Zaktualizuj stronę: zadania dotyczące dokumentacji technicznej na potrzeby hackathonów. (do wykonania: dodaj odpowiednie zadania do tej strony w trakcie trwania projektu)

  • Tworzenie centrum dla autorów treści technicznych

    • Utwórz stronę docelową z linkami do przydatnych stron i materiałów.
    • Dodaj niezbędne linki do nowej i dotychczasowej strony, aby ułatwić sobie poruszanie się między nimi.

Tydzień 6 (7–13 października)

  • Utwórz następujące dokumenty dotyczące tworzenia filmów na potrzeby MediaWiki:

    • Szybki przewodnik użytkownika dotyczący tworzenia ogólnego screencastu, który odsyła do projektu Screencast.
    • Szablony: instrukcje korzystania z oprogramowania lub narzędzia; samouczki dotyczące tworzenia nowych narzędzi.

  • Utwórz listę pomysłów na screencasta dla MediaWiki.

Tydzień 7 (14–20 października)

  • Pracuj nad filmem „Wprowadzenie do Phabricatora”:

    • Użyj szablonu (utworzonego w poprzednim tygodniu), aby napisać skrypt.
    • Oszacuj skuteczność szablonu i w razie potrzeby go ulepszaj.
    • Uzyskaj opinię i sfinalizuj wersję roboczą.

Tydzień 8 (21–27 października)

  • Opublikuj film „Introduction to Phabricator”:

    • Wybierz i zainstaluj oprogramowanie.
    • Skonfiguruj środowisko i utwórz screencast.
    • Zanotuj napotkane problemy i ich rozwiązania.

Tydzień 9 (28 października – 3 listopada)

  • Ulepsz dokumentację projektu Screencasta:

    • Przeanalizuj strukturę witryny i omów potrzeby wprowadzenia zmian.
    • Przejrzyj wymienione oprogramowanie.
    • Sprawdź i zaktualizuj listę oprogramowania.

Tydzień 10 (4–10 listopada)

  • Dalsze ulepszanie dokumentacji projektu screencast:

    • Ocenianie i ulepszanie samouczka i skryptów.
    • Przejrzyj galerię screencastów.

Tydzień 11 (11–17 listopada)

  • Wykonaj zadania związane z dokumentacją projektu Screencasta:

    • Znajdź i dodaj nowe filmy do galerii.
    • Wprowadź niezbędne zmiany strukturalne.

Tydzień 12 (18–24 listopada)

  • Zajmij się oczekującymi zadaniami.

  • Napisz raport końcowy:

    • Zapoznaj się z raportami co 2 tygodnie lub codziennie i zbierz wymagane informacje.
    • Zaplanuj strukturę raportu i napisz wersję roboczą.
    • Na podstawie opinii mentora ulepsz i sfinalizuj wersję roboczą.

Tydzień 13 (25–29 listopada)

  • Prześlij końcowy raport i ocenę mentora.

6. Śledzenie postępów

Codzienne informacje o postępach będą przekazywane mentorom za pomocą Zulip. Społeczność Wikimedia może śledzić moje postępy za pomocą Phabricatora lub co 2 tygodnie publikowanych raportów projektowych.

7. Inne zobowiązania

Jestem studentem studiów stacjonarnych, a mój semestr jesienny pokrywa się z okresem Season of Docs. Dlatego moje zobowiązania obejmują egzaminy na uczelni.

Pierwszy egzamin wewnętrzny: 18–24 sierpnia

Drugi egzamin wewnętrzny: od 29 września do 6 października

Egzamin kończący semestr: od 11 do 30 listopada

Planuję też wziąć udział w pierwszej konferencji publicznej, PyCon India, która odbędzie się w dniach 12–15 października. Wszystko dzięki temu, że w tym roku konferencja odbędzie się w dogodnym dla mnie miejscu. To świetna okazja, aby poznać nowych ludzi i porozmawiać na ciekawe tematy.

Aby zarządzać tymi zobowiązaniami, w odpowiednich tygodniach harmonogram wstępny zawiera mniej istotne zadania. W jednym semestrze zamierzam zdobyć maksymalnie 20 punktów podstawowych, aby mieć wystarczająco dużo czasu na opracowanie dokumentów. (zwykły student zdobywa średnio 25 punktów za semestr)