Projekt Wikimedia Foundation

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:
Wikimedia Foundation
Pisarz techniczny:
Pavithra Eswaramoorthy
Nazwa projektu:
Ulepszanie dokumentacji dla twórców dokumentacji technicznej i filmów w Wikimedia
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

1. O mnie

Zetknęłam się z oprogramowaniem open source kilka miesięcy temu i prawie natychmiast poczułam się przytłoczona jego nieograniczonym zakresem. Mam problem z przeprowadzeniem się licznych projektów, ale dowiedziałam się więcej o inicjatywach open source, takich jak Google Summer of Code czy Outline. Sezon Dokumentów Google wydawał mi się ciekawy, a pomysły na projekt Fundacji Wikimedia wzbudziły moją ciekawość, więc zacząłem go szukać.

Moja dotychczasowa podróż była równie ekscytująca i zrozumiała. Na każdym kroku pojawiają się pytania: „Zaczekaj, co?”, „Rozumiem?” i „Czy mam to skomentować?”. Społeczność Wikimedia wspiera mnie na każdym etapie. Każdego dnia odkrywam coś nowego, od edytowania stron po tworzenie rozszerzeń.

Zgodnie z oczekiwaniami proces aplikacji stał się moją bramą dla społeczności open source. Ta propozycja została zainspirowana moimi moimi wcześniejszymi doświadczeniami.

2. Projektach

2.1. Konspekt

Ten projekt ma na celu ulepszenie dokumentacji dla autorów tekstów technicznych i potencjalnych kamerzystów w Wikimediach. Dopracowany zestaw wskazówek dotyczących dokumentacji technicznej pomoże w ulepszaniu ogólnej dokumentacji, a odniesienia do tworzenia screencastów umożliwią efektywne zaprezentowanie funkcji oprogramowania. Dotychczasową dokumentację tych obszarów można wzbogacić, aby były bardziej przydatne zarówno dla nowych, jak i doświadczonych współtwórców. W oparciu o tę sieć przydatnych zasobów będziemy stosować stopniowe podejście.

2.2. Twoje zobowiązanie

  • T197006 [https://phabricator.wikimedia.org/T197006] — Ulepszona dokumentacja dla dokumenterów Wikimedia:

    • Dodaj wskazówki i przykłady do dokumentacji/przewodnika stylistycznego. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Dodaj informacje związane z MediaWiki do wybranych gatunków za pomocą szablonów i sugestii dokumentacji technicznej: podręczniki użytkownika, instrukcje, krótkie przewodniki, informacje o wersji i pliki README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Testowanie i ulepszanie wskazówek dotyczących określania priorytetów w dokumentacji technicznej. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Opracuj strategię gromadzenia treści dla różnych rodzajów dokumentacji.
    • Opracuj strategię komunikacji i współpracy na potrzeby dokumentacji MediaWiki.
    • Utworzyć listę kontrolną, dzięki której autorzy mogą przeglądać swoje dokumenty przed ich opublikowaniem.
    • Rozszerz strukturę dokumentacji dla nowych autorów tekstów technicznych. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Przygotuj listę zadań z dokumentacją techniczną, które są odpowiednie do wykorzystania w ramach hackathonów. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Utwórz centrum dla twórców technicznych, które prowadzi do przydatnych materiałów.

  • Popraw dokumentację dla filmowców MediaWiki:

    • Utwórz krótki przewodnik użytkownika z ogólnym screencastem.
    • Projektuj szablony screencastów przeznaczone specjalnie dla MediaWiki na potrzeby przewodników i samouczków.

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

2.3. Cel rozciągania

  • Sprawdź ponownie treść 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ą używane będą kanały Wikimedia i adres e-mail. Dyskusje o konkretnych zadaniach będą się odbywać w sekcji komentarzy do zadań fabrykacyjnych.

4. Dyskusja

Ten projekt jest zasadniczo podzielony na 2 fazy:

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

(ii) Twórz szablony przydatne dla potencjalnych filmowców.

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

W przeszłości podjęto szereg inicjatyw mających na celu ulepszenie dokumentacji MediaWiki, ale na różne sposoby. 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

Widać już, że większy zestaw zasobów dla pisarzy technicznych będzie miał bezpośredni wpływ na tworzone przez nich dokumenty.

Oto fragment tworzonego co 2 tygodnie raportu Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/ dotyczącego stażysty z Workspacey w 2018 roku:

„Przewodnik stylistyczny MediaWiki daleki jest od doskonałości, zwłaszcza, gdy w dużej mierze opiera się na odwołaniach zewnętrznych bez podkreślania, które praktyki uważa za najlepsze. Niestety ten problem nie jest ograniczony wyłącznie do MediaWiki, o czym piszą inne dokumenty, takie jak sprawdzone metody dotyczące tłumaczeń. Dla pisarzy, którzy mają do czynienia z brakiem dobrych i wiarygodnych zasobów do wykonania swojej pracy, napotykają oni trudności z określeniem grupy docelowej i właściwym stylem pisania. A użytkownicy, zwłaszcza nowi użytkownicy, mogą mieć problemy ze zrozumieniem nowych koncepcji i procesów”.

Dokument T197006 [https://phabricator.wikimedia.org/T197006] także rzuca światło na niektóre obszary dokumentacji technicznej, które wymagają ulepszenia. Oczywiście, od czego należy zacząć, należy przejść do sekcji Dokumentacja/Przewodnik po stylu.

Po opracowaniu lepszego przewodnika stylistycznego zaplanujemy kolejny zestaw dokumentów, które przeprowadzą twórców technicznych przez poszczególne etapy pisania technicznego. Dokumenty muszą być zrozumiałe dla początkujących, a jednocześnie zawierać wszystkie niezbędne informacje dla autorów.

Etap przygotowania jest prawdopodobnie najważniejszy, ponieważ stanowi podstawę do stworzenia dokumentu. Aby pomóc twórcom na tym etapie, przygotowaliśmy dokumentację z opisem skutecznych sposobów gromadzenia istotnych informacji i uporządkowywania ich struktury za pomocą szablonów.

Następnie przychodzi etap pisania. Scenarzyści otrzymują przykłady dobrych prac, aby automatycznie podnosić poprzeczkę. Ponadto tworzona jest lista kontrolna z zestawem podstawowych kryteriów, które musi spełniać każdy dokument. Ułatwi to autorom przeglądanie dokumentów przed ich opublikowaniem.

Nawet jeśli mają oni dostęp do tych dokumentów, nowi autorzy techniczni potrzebują dodatkowej pomocy, a my musimy jej im ją udzielić. Przewodnik dla nowych pisarzy technicznych został dopracowany, a lista zadań odpowiednich do hackathonów jest dobierana na podstawie poziomu trudności.

Na koniec testujemy i ulepszamy dokument opisujący proces zarządzania dokumentacją i jej utrzymywania.

Na koniec tej fazy utworzymy centrum pomocy technicznej, zasobów, przykładów, sugestii i szablonów służących do tworzenia dokumentacji.

(ii) Twórz szablony przydatne dla potencjalnych filmowców.

„Jednym z najtrudniejszych sposobów na nauczenie się wszystkiego, co zawiera grafikę, jest czytanie zwykłego tekstu. Wyobraźmy sobie również, co się stanie, jeśli instrukcja odnosi się do niewłaściwej wersji oprogramowania. W przypadku instrukcji w samym tekście odtworzenie serii czynności z powodu zmiany menu i słownictwa w aplikacji ze względu na brak wszystkich przydatnych wskazówek może okazać się niemożliwe.

Najlepiej będzie, jeśli nauczysz się tego, gdy przysiada ekspert. Screencasty łączą statyczną grafikę z ekspertem w pobliżu. Otrzymujemy wizualną, poruszającą się prezentację o przyjaznym głosie. Możemy także umieścić na ekranie adnotacje tekstowe i animacje. Zaletą screencastów jest to, że można je odtwarzać o każdej porze każdego dnia.

Do screencasta możemy też dodać przetłumaczone napisy, aby mogły je obejrzeć osoby, które nie znają języka rodzi, lub zastąpić ścieżkę audio innym językiem”.

W powyższym fragmencie z artykułem „The Screencasting Handbook” [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] Ian Ozsvald wyjaśnia znaczenie screencastów. Może być szczególnie przydatna w przypadku samouczków dotyczących konfigurowania środowiska programistycznego MediaWiki, tworzenia rozszerzeń, używania narzędzia Gerrit i nie tylko.

Podobnie jak w przypadku szablonów dokumentów, stosowanie standardowego szablonu screencastów zwiększa ujednolicenie treści i zapewnia widzom lepsze wrażenia. Ponadto stanowi platformę, na której potencjalni filmowcy mogą rozpocząć pracę. Dlatego opracowaliśmy krótki przewodnik użytkownika z szablonami do tworzenia filmów wprowadzających i samouczków. Dokumenty te zawierają wskazówki dotyczące dogłębnego zakresu pojęć, które warto omówić, oraz kilka screencastów z serwisu MediaWiki.

Najlepszym sposobem na przetestowanie powyższego szablonu i przygotowanie się do realizacji celu rozszerzonego jest utworzenie screencasta za pomocą narzędzi i szablonów. Dlatego stworzyliśmy screencast „Wprowadzenie do aplikacji Phabricator”, który przedstawia podstawy korzystania z aplikacji Phabricator. W ten sposób wyróżnisz też obszary, które wymagają omówienia.

Na koniec omawiamy i aktualizujemy najważniejsze źródło materiałów dla filmowców Wikimedia – WikiProject Screencast.

5. Wstępny termin

Okres integrowania społeczności (1 sierpnia–1 września)

  • Szczegółowo przeanalizuj projekt z moimi mentorami.

  • Porozmawiaj na te tematy:

    • Częstotliwość sprawdzania zadań.
    • Udostępniaj harmonogramy i decyduj o tygodniowym/codziennym przepływie pracy.
    • Narzędzia i zasoby, których można użyć.
    • Co 2 tygodnie i dzienne raporty z projektu.

  • Utwórz wymagane zadania i podzadania w aplikacji Phabricator.

  • Tworzenie wersji roboczych w celu zrekompensowania osobistych zobowiązań na etapie opracowywania dokumentów.

Tydzień 1 (2–8 września)

  • Ulepsz dokumentację/przewodnik dotyczący stylu:

    • Należy skupić się na głównej części witryny, aby zilustrować sprawdzone metody i standardy w serwisie MediaWiki.
    • Podaj przykłady dobrych prac i zwiększ widoczność powiązanych stron.

  • Ulepszanie przewodnika dla nowych autorów tekstu o tematyce technicznej:

    • Rozwiń strukturę dokumentacji.

Tydzień 2 (9–15 września)

  • Nadaj priorytet dokumentacji technicznej:

    • Ocena tablicy roboczej dokumentacji; znajdowanie przykładów dobrych opisów zadań i ustalania priorytetów.
    • Badanie trendów i zanotowanie typowych trudności.
    • Skorzystaj z informacji i przykładów, aby udokumentować standardy ustalania priorytetów.

Tydzień 3 (16–22 września)

  • Utwórz te dodatkowe dokumenty dla autorów tekstów technicznych:

    • Lista kontrolna ułatwiająca zapoznanie się z dokumentacją techniczną przed publikacją
    • Sposoby efektywnego gromadzenia treści z różnych gatunków dokumentów.

Tydzień 4 (23–29 września)

  • Dodaj informacje na temat pisania w najpopularniejszych gatunkach MediaWiki do szablonów i sugestii dokumentacji technicznej:

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

  • Dodanie wskazówek pozwalających poprawić 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)

  • Ulepszenie dokumentacji dotyczącej wprowadzania nowych współpracowników:

    • Zaktualizuj stronę: zadania związane z dokumentacją techniczną hackathonów. (Do zrobienia: dodawaj na tej stronie odpowiednie zadania w okresie trwania projektu)

  • Centrum twórców technicznych

    • Utworzyć stronę docelową z linkami do przydatnych stron i materiałów.
    • Dodaj niezbędne linki do nowych i istniejących stron, 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 wideo dla serwisu MediaWiki:

    • Krótki przewodnik użytkownika na temat tworzenia ogólnego screencasta wskazującego projekt Screencast.
    • Szablony: instrukcje korzystania z oprogramowania/narzędzia, samouczki na temat tworzenia nowych narzędzi.

  • Utwórz listę pomysłów na screencasty do MediaWiki.

Tydzień 7 (14–20 października)

  • Opracuj film „Wprowadzenie do Phabricator”:

    • Użyj szablonu (utworzonego w poprzednim tygodniu) do utworzenia wersji roboczej skryptu.
    • Oszacuj wydajność szablonu i w razie potrzeby popraw go.
    • Poproś o 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.
    • Zapisz napotkane problemy i ich rozwiązania.

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

  • Ulepszaj dokumentację projektu Screencast:

    • Zbadaj strukturę i ustal, czy nie warto wprowadzić zmian.
    • Sprawdź wymienione oprogramowanie.
    • Zapoznaj się z listą programów i zaktualizuj ją.

Tydzień 10 (4–10 listopada)

  • Ulepszaj dokumentację projektu Screencast:

    • ocenić i ulepszyć samouczek oraz skrypty;
    • Przejrzyj galerię screencastów.

Tydzień 11 (11–17 listopada)

  • Wykonaj pracę w dokumentacji projektu Screencast:

    • znajdować i dodawać nowsze filmy do galerii;
    • Wprowadź niezbędne zmiany strukturalne.

Tydzień 12 (18–24 listopada)

  • Przeprowadź pracę nad oczekującymi zadaniami.

  • Napisz raport końcowy:

    • Przeglądaj raporty dzienne lub przeprowadzane co 2 tygodnie i zbieraj wymagane informacje.
    • Zaplanuj strukturę raportu i napisz wersję roboczą.
    • Popraw i sfinalizuj wersję roboczą na podstawie opinii mentora.

Tydzień 13 (25–29 listopada)

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

6. Śledzenie postępów

Codzienne informacje o postępach będą przekazywane moim mentorom przez Zulip. Społeczność Wikimedia dotycząca moich postępów może śledzić moje postępy za pomocą platformy Phabricator lub raportów zgłaszanych co 2 tygodnie.

7. Inne zobowiązania

Uczę się na studia w pełnym wymiarze godzin, a moje jesienne semestry nakładają się na oś czasu sezonu Dokumentów. Dlatego też moje zobowiązania obejmują egzaminy na studiach.

Pierwszy egzamin wewnętrzny: 18–24 sierpnia

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

Egzamin na koniec semestru: od 11 do 30 listopada

Planuję też wziąć udział w pierwszej publicznej konferencji PyCon India, która od 12 do 15 października odbędzie się w dniach 12–15 października. Uważam, że to świetna okazja do poznania nowych ludzi i dyskusji.

Aby ułatwić sobie zarządzanie tymi zobowiązaniami, wstępny harmonogram obejmuje mniej ważne zadania w poszczególnych tygodniach. Zamierzam zdobyć nie więcej niż 20 podstawowych punktów w jednym semestrze, aby mieć wystarczająco dużo czasu na opracowanie dokumentacji. (Stały uczeń uzyskuje średnio 25 punktów na semestr)