Projekt VLC

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:
VLC
Pisarz techniczny:
Abhishek Pratap Singh
Nazwa projektu:
Kontynuowanie modernizacji dokumentacji użytkownika VLC
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

BIEŻĄCY STAN DOKUMENTACJI

Dokumentacja użytkownika VLC jest obecnie modernizowana i aktualizowana. Trwa przejście z starszej dokumentacji opartej na wiki[1] na nowoczesną dokumentację użytkownika opartą na Sphinxie[2] hostowaną na ReadTheDocs.

DOCELOWI ODBIORCY

Odbiorcami są ciekawscy użytkownicy, którzy chcą poznać funkcje odtwarzacza VLC wykraczające poza możliwości zwykłego odtwarzacza. W pewnym stopniu poradnik ten będzie też pomocny deweloperom. Dlatego planuję uwzględnić zarówno instrukcje dotyczące interfejsu graficznego (wraz z odpowiednimi obrazami), jak i metody oparte na interfejsie wiersza poleceń (wraz z fragmentami kodu), aby użytkownik końcowy miał możliwość wyboru.

Uważam, że język dokumentacji (zwłaszcza sekcja interfejsu graficznego) powinien być stonowany na tyle, aby osoba z minimalną znajomością obsługi komputerów mogła zrozumieć i zastosować się do poradnika. Z drugiej strony nie powinien być zbyt długi ani zbyt obszerny (zwłaszcza sekcja CLI), aby nie zniechęcać programistów.

Odpowiedniego balansu można dokonać, wspominając wymagania wstępne na początku strony lub pozostawiając opcjonalne sekcje, które doświadczeni użytkownicy mogą pominąć.

W przypadku tłumaczeń odbiorcami docelowymi są deweloperzy i użytkownicy VLC, którzy dobrze znają język angielski i język, na który mają przetłumaczyć tekst.

NARZĘDZIA

Nowa dokumentacja jest tworzona przez Sphinxa i hostowana na ReadTheDocs, a system kontroli wersji jest implementowany w GitLab. Miałem już pewne doświadczenie w korzystaniu z Git i GitHub, co pomogło mi w zapoznaniu się z GitLab, chociaż niektóre funkcje wymagały nauki.

Jeśli chodzi o Sphinx, czytałem o nim, gdy jakiś entuzjasta oprogramowania open source zauważył, jak wiele organizacji używa go do tworzenia dokumentacji (w tym przykład narzędzia Blender, w którym opracowano instrukcję obsługi Sphinx[3] i dokumentację API[4]).

Znam trochę ReadTheDocs, które jest dobrym narzędziem do zarządzania wersjami i hostowania dokumentacji technicznej. Dzięki temu udało mi się bez większych problemów stworzyć dokumentację VLC i jestem zaznajomiony z reStructured Text, czyli formatowaniem, którego użyto.

W przypadku tłumaczeń VLC używa Babel do generowania plików .po w celu implementacji i18n i l10n. Obecnie zapoznaję się z przepływem pracy w Babel i tworzeniem plików .mo za pomocą Sphinx.

Zamierzam wykorzystać okres nawiązywania więzi, aby lepiej poznać zawiłości wymienionych powyżej narzędzi.

MATERIAŁY DO DOSTARCZENIA I HARMONOGRAM CZASOWY NA TYDZIEŃ

W ramach projektu z 2019 r. zostały już uwzględnione niektóre elementy instalacji, interfejsu, dźwięku, wideo, odtwarzania itp. (większość podstawowych funkcji). Dlatego w ramach projektu na 2020 r. chcę zaktualizować i popracować nad sekcją dotyczącej zaawansowanego korzystania z dokumentacji dla użytkowników.

WYNIK 1 [Tydzień 1–2]: zaktualizuj dokumentację transkodowania zgodnie z opisem w punkcie 7[5].

  • Transkodowanie
  • Transkodowanie wielu filmów
  • Dodaj logo
  • Łączenie filmów
  • Wyodrębnij dźwięk i Wyodrębnij dźwięk z pliku
  • Kopiowanie płyty DVD

WYNIK 2 [tydzień 3–4]: zaktualizuj sekcję „Używanie VLC jako wtyczki internetowej”[6] i przeprowadź testy w przeglądarkach Firefox 77, Chrome 83 i Edge 83.

  • Tworzenie stron internetowych z filmami
  • Atrybuty tagu do wklejania
  • Opis interfejsu JavaScript API

ZADANIE 3 [Tydzień 5]: przetestuj polecenia interfejsu wiersza poleceń[7] i wprowadz odpowiednie zmiany.

  • Strumienie
  • Wybór modułów
  • Opcje dotyczące konkretnego produktu
  • Filtry

Tydzień 6.: tydzień na przygotowanie 3 wymaganych elementów.

WYNIK 4 [tydzień 7–8]: przygotowanie do tłumaczenia. Oprócz aktualizacji przygotuję też tłumaczenia na inne języki. Jest to ważne, ponieważ po przetłumaczeniu dokumentację będą mogli czytać użytkownicy, którzy nie znają angielskiego (a oprócz tego VLC będzie o krok bliżej osiągnięcia światowej dominacji[8]).

Jak wspomniano w sekcji „Narzędzia” w propozycji, VLC używa obecnie Babel do generowania plików .po na potrzeby tłumaczeń. Dokumentuję tę procedurę dla użytkownika/wolontariusza, aby:

  • Pobierz dokumentację podstawową i utwórz ją lokalnie.
  • Użyj Babel do wygenerowania wymaganych plików.
  • Wpisz tłumaczenia ciągów znaków.
  • Kompilowanie przetłumaczonej dokumentacji za pomocą Sphinx.
  • Zatwierdź zmiany.

WYNIK 5 [tydzień 9–10]: przygotuj dokumentację modułów. Zgodnie z uzgodnieniami z mentorami planuję przygotować dokumentację modułów w 2 częściach.

Część I: tworzenie plików zbliżonych do modułów za pomocą skryptu, który wyszukuje prawidłowe opcje w kodzie źródłowym i wyodrębnia ich użycie w jednym wierszu (oraz wartości domyślne) ze odpowiednich stron Wiki. Będzie to podstawowa wersja robocza.

Część II: tworzenie struktury dla konkretnej platformy, która łączy wszystkie moduły, wtyczki i opcje dla danej platformy (Windows, a jeśli czas na to pozwoli, także Fedora).

Tworzenie plików w pobliżu modułów zapewni, że dokumentacja będzie znajdować się blisko kodu źródłowego. Dokumentacja modułów składa się z plików utworzonych w części I i struktury z części II jako odniesienia.

Pliki utworzone za pomocą automatyzacji wymagają sprawdzenia, ale priorytetem jest stworzenie funkcjonalnej platformy. Gdy to zrobisz, sprawdzę pliki, aby potwierdzić opcje. Ramy są priorytetem, ponieważ gdy tylko będą dostępne, deweloperzy i konserwatorzy będą mogli zacząć je rozwijać, dodając odpowiednie przypadki użycia.

DOSTAWA BONUSU [Tydzień 11]: przygotuj się do premiery wersji 4.0. Jeśli realizacja projektu będzie przebiegać zgodnie z harmonogramem, mogę zaproponować bonus. Jak już zostało to omówione z mentorami, przygotowanie się do wydania wersji 4.0 wymaga posiadania stabilnej i prawie kompletnej dokumentacji wersji 3.0.

Dlatego, aby zweryfikować i zaktualizować opisane w nich metody, zapoznaj się z już ukończoną dokumentacją z tych sekcji:

  • Podstawowe informacje: multimedia, odtwarzanie, dźwięk, wideo, napisy, skróty klawiszowe, nagrania, ustawienia, porady i wskazówki.
  • Zaawansowane zastosowania: odtwarzacz, interfejs, transkodowanie, streaming, nietypowe przypadki.
  • Dodatki: rozszerzenia, skórki.

Tydzień 12: Tydzień buforów dotyczący 3 powyższych celów + raporty końcowe.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO REALIZACJI TEGO PROJEKTU?

Jako pasjonat technologii mam doświadczenie w korzystaniu z oprogramowania i jego testowaniu, a czasem także w próbach zrozumienia kodu źródłowego. Kiedy próbowałem zrozumieć bazę kodu organizacji typu open source, po raz pierwszy zrozumiełem, jak ważna jest dokumentacja. Poza tym jako miłośnik muzyki mam duże doświadczenie w dostosowywaniu VLC.

Poza tym przez całe życie zajmuję się badaniami i pisaniem. Jeśli czegoś nie napiszę, nigdy tego nie rozumiem. Dzięki temu nawykowi sprawnie zanotuję i udokumentuję.

To połączenie sprawia, że jestem odpowiednią osobą do tworzenia dokumentacji technicznej. Mogę poznać aspekty techniczne i dokumentować swoje odkrycia i procesy w sposób zrozumiały dla użytkowników.

Linki: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/pl/latest/index.html [3] https://docs.blender.org/pl/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35