Projekt VLC

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

Podsumowanie projektu

Organizacja open source:
VLC
Pisarz techniczny:
Abhishek Pratap Singh
Nazwa projektu:
Kontynuuj modernizację dokumentacji użytkownika VLC
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

OBECNY STAN DOKUMENTACJI

Dokumentacja użytkownika VLC jest w trakcie modernizacji i aktualizacji. Trwa proces przechodzenia ze starszej dokumentacji opartej na wiki[1] na nowoczesną dokumentację dla sfinksów[2] hostowaną w ReadTheDokumentacja.

DOCELOWI ODBIORCY

Docelowi odbiorcy to ciekawi użytkownicy, którzy chcą poznać funkcje odtwarzacza multimedialnego VLC poza zwykłym odtwarzaczem, a do pewnego stopnia pomagają też programistom, ponieważ są prostym przewodnikiem. Dlatego zamierzam uwzględnić instrukcje oparte na GUI (wraz z obrazami, jeśli ma to zastosowanie), jak i metody oparte na interfejsie wiersza poleceń (wraz z fragmentami kodu), aby zapewnić użytkownikowi swobodę wyboru.

Uważam, że język dokumentacji (zwłaszcza sekcji GUI) powinien być na tyle stonowany, aby osoba nominalna posiadająca styczność z komputerami operacyjnymi mogła go zrozumieć i zastosować. Z drugiej strony nie powinno być zbyt długie ani wyjaśniać (zwłaszcza sekcji interfejsu wiersza poleceń), aby koderzy mogli stracić zainteresowanie.

Aby osiągnąć odpowiednie zrównoważone wymagania, wspomnij o wymaganiach wstępnych na początku strony lub zachowaj opcjonalne sekcje, które osoby doświadczonych mogą pominąć.

Docelowi odbiorcy to deweloperzy i użytkownicy VLC, którzy dobrze znają język angielski i język, na który będą tłumaczyć.

NARZĘDZIA

Nowa dokumentacja jest tworzona przez Sphinx i hostowana w ReadTheDokumentacja, a system kontroli wersji jest zaimplementowany w GitLab. Miałem(-am) w przeszłości doświadczenie z GitLab i GitHubem, które pomogły mi przyzwyczaić się do działania GitLab, chociaż niektóre funkcje wymagały trochę czasu.

Jeśli chodzi o Sfinksa, czytałem o tym, gdy kolega z branży open source zauważył, ile organizacji używa jej do tworzenia dokumentacji (przykład: firma Blender, która wykorzystuje Sphinxa do opracowania instrukcji obsługi[3] i dokumentacji API[4]).

Byłem(am) w pewnym stopniu obecny w programie ReadTheDokumentacja – dobrym narzędziem do obsługi wersji i hostowania dokumentacji technicznej. W związku z tym udało mi się stworzyć dokumentację VLC bez większego problemu i znać tekst przeformatowany oraz użyte formatowanie.

Tłumaczenia korzystają z narzędzia Babel do generowania plików .po, by wdrożyć i18n oraz l10n. Obecnie dowiaduję się więcej o przepływie pracy Babel i o tym, jak tworzyć pliki .mo za pomocą Sphinxa.

Zamierzam wykorzystać okres więzi, aby lepiej poznać tajniki wspomnianych wyżej narzędzi.

DOSTAWY I TYGODNIOWE OŚ CZASU DOSTAWY

W ramach projektu z 2019 r. program obejmuje części instalacji, interfejsu, audio, wideo, odtwarzania itp. (większość podstawowych funkcji). W związku z tym w ramach projektu na 2020 rok chcę zaktualizować sekcję dotyczącą zaawansowanych zastosowań w dokumentacji dla użytkowników.

MOŻLIWA DO DOSTAWY 1 [Tydzień 1–2]: aktualizacja dokumentacji transkodowania zgodnie z opisem w punkcie 7[5].

  • Transkoduj
  • Transkoduj wiele filmów
  • Dodaj logo
  • Łączenie filmów
  • Wyodrębnianie dźwięku z pliku
  • Zgraj DVD

WYŚWIETLANIE 2 [tydzień 3–4]: aktualizacja z użyciem VLC jako wtyczki internetowej[6] podczas testowania w Firefoksie 77, Chrome 83 i Edge 83.

  • Tworzenie stron internetowych za pomocą filmów
  • Atrybuty tagu umieszczenia
  • Opis interfejsu JavaScript API

MOŻLIWOŚĆ WYŚWIETLANIA 3 [Tydzień 5]: przetestuj polecenia interfejsu wiersza poleceń[7] i odpowiednio je zaktualizuj.

  • Strumienie
  • Wybór modułów
  • Opcje dla konkretnego elementu
  • Filtry

Tydzień 6: Tydzień buforowania w przypadku 3 wymienionych powyżej celów.

DOSTARCZANIE 4 [Tydzień 7–8]: Przygotuj się do tłumaczenia. Oprócz aktualizacji przygotuję się do tłumaczenia na inne języki. Jest to ważne, ponieważ po tłumaczeniu użytkownicy, którzy nie znają angielskiego, będą mogli przeczytać dokumentację (na marginesie warto zauważyć, że VLC przybliżałoby do dominacji nad światem[8]).

Jak wspomnieliśmy w sekcji Narzędzia oferty pakietowej, VLC obecnie używa Babel do generowania plików .po do tłumaczenia. Udokumentuję ten proces dla użytkownika/wolontariusza, aby:

  • Pobierz i stwórz podstawową dokumentację lokalnie.
  • Wygeneruj wymagane pliki przy użyciu Babel.
  • Wpisz tłumaczenia ciągów tekstowych.
  • Tworzenie przetłumaczonej dokumentacji przy użyciu Sphinxa.
  • Zatwierdź zmiany.

DOSTARCZANIE 5 [Tydzień 9–10]: przygotuj się do udostępnienia dokumentacji modułów. Zgodnie z ustaleniami z mentorów planuję przygotować dokumentację modułów w 2 częściach.

Część – I: tworzenie plików w pobliżu modułów za pomocą skryptu, który szuka prawidłowych opcji w bazie kodu i wyodrębnia ich jednowierszowe użycie (i wartości domyślne) z odpowiednich stron wiki. Będzie to podstawowa wersja robocza.

Część – II: budowanie struktury związanej z platformą, która łączy wszystkie moduły, wtyczki i opcje dla danej platformy (Windows, a jeśli pozwala na to czas, także dla Fedora).

Tworząc pliki w pobliżu modułów, będziesz mieć pewność, że dokumentacja będzie jak najbardziej zbliżona do kodu źródłowego. Kierując się podejściem u dołu, główną dokumentację modułów tworzy się, łącząc pliki utworzone w Części I I, używając jako odniesienia struktury z Części – II.

Pliki utworzone w ramach automatyzacji wymagają sprawdzenia, ale pierwszym priorytetem jest stworzenie funkcjonalnej platformy. Gdy to zrobisz i w zależności od dostępnego czasu, sprawdzę pliki, aby sprawdzić dostępne opcje. Traktujemy ją priorytetowo, ponieważ od momentu jej udostępnienia deweloperzy i opiekunowie mogą zacząć dodawać do niej odpowiednie przypadki użycia.

DOSTAWA BONUSOWA [Tydzień 11]: przygotuj się do udostępnienia wersji 4.0. Jeśli realizacja projektu przebiega zgodnie z harmonogramem, chcę zaproponować bonus. Jak już wspominaliśmy z mentorami, przygotowanie się do wprowadzenia wersji 4.0 wymaga posiadania stabilnej i prawie kompletnej dokumentacji do wersji 3.0.

Dlatego zapoznam się z dokumentacją dotyczącą poniższych sekcji, aby zweryfikować i zaktualizować zastosowane metody:

  • Podstawowe zastosowania: multimedia, odtwarzanie, dźwięk, film, napisy, klawisze skrótów, nagrania, ustawienia, wskazówki i porady.
  • Zaawansowane zastosowania: odtwarzacz, interfejs, transkodowanie, strumieniowe przesyłanie danych, nietypowe przypadki.
  • Dodatki: rozszerzenia, skórki.

Tydzień 12: Tydzień buforowania w związku z 3 wymienionymi powyżej treściami i raportami końcowymi.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO TEGO PROJEKTU?

Jako entuzjasta technologii mam doświadczenie w korzystaniu z oprogramowania i testowaniu go. Czasami staram się wyciągnąć sens z życia w ich bazach kodu. Próba zrozumienia bazy kodu organizacji open source po raz pierwszy w pełni zdała sobie sprawę, jak ważna jest dokumentacja. Poza tym jako entuzjasta muzyki mam już spore doświadczenie w dostosowywaniu usług do VLC. :)

Poza tym całe życie pracuję jako naukowiec i pisarka. Chyba że coś spiszę, to nigdy tego nie zrozumiem, a ten nawyk sprawił, że jestem sprawną twórczynią notatek i dokumentów.

Połączenie tych 2 nawyków sprawia, że najlepiej pasuję do dokumentacji technicznej. Mogę zaznajomić się z kwestiami technicznymi i dokumentować wyniki/procesy w sposób zrozumiały dla użytkowników.

Linki: [1] https://wiki.videolan.org/Documents:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/pl/latest/index.html [3] https://docs.blender.org/manual/pl/latest/Dokumentacja[4] https://docs.blender.org/api/current/index.html [5] https://code.video.org