Projekt VideoLAN

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

Podsumowanie projektu

Organizacja open source:
VideoLAN
Pisarz techniczny:
Ediong Anny Asikpo
Nazwa projektu:
Moderowanie (nadpisywanie) dokumentacji użytkownika VLC
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

Streszczenie

Dokumentacja dla użytkowników ma pomagać użytkownikom w korzystaniu z produktów lub usług. Dobra dokumentacja użytkownika jest bardzo ważna, ponieważ umożliwia użytkownikom nauczenie się korzystania z oprogramowania, jego funkcji, porad i wskazówek, a także rozwiązywania typowych problemów. Obniża też koszty pomocy i jest częścią tożsamości firmy: dobra dokumentacja użytkownika jest oznaką prawidłowego działania usługi – zespołu programistów.

Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak wykonywać te czynności skutecznie i wydajnie. Dokumentacja użytkownika może odegrać kluczową rolę w zapewnieniu sukcesu usługi, ponieważ dobra komunikacja to podstawa każdej firmy i produktu, a doskonała dokumentacja pozwala z łatwością postawić ją w formie łatwej do opanowania przez każdego.

W momencie tworzenia tego tekstu dokumentacja użytkownika VLC była odczytywana 4 634 065 razy, a odtwarzacz multimediów VLC co miesiąc jest pobierany ze strony głównej około 23 milionów razy. Oznacza to,że wiele osób na całym świecie korzysta z tego odtwarzacza i może chcieć przeczytać jego dokumentację,aby dowiedzieć się, jak z niego korzystać. Dokumentacja użytkownika odtwarzacza multimediów VLC jest jednak obecnie nieaktualna i niekompletna (ostatnia modyfikacja miała miejsce 28 października 2015 r.). Społeczność VideoLAN chce wykorzystać ten projekt do ulepszenia dokumentacji dla użytkowników, aby zapewnić użytkownikom płynną obsługę podczas korzystania z odtwarzacza.

OBECNY STAN

Dokumentacja użytkownika jest obecnie dostępna na stronie wiki. Jest ono przestarzałe, niekompletne, trudne do nawigacji lub znalezienia, nie obejmuje informacji na temat bieżącej wersji odtwarzacza i może zostać przetłumaczone tylko na język niemiecki, co stanowi poważny problem dla osób nieznających języka angielskiego.

DLACZEGO PROPONOWANA DOKUMENTACJA UŻYTKOWNIKÓW JEST ULEPSZONĄ W SIECI OBECNEJ?

Opracowana dokumentacja dla użytkownika zostanie opracowana w celu poprawy jego wydajności, spójności i spokoju ducha. Będzie on zawierać pisemne przewodniki i związane z nimi obrazy, instrukcje i objaśnienia dotyczące korzystania z poszczególnych funkcji odtwarzacza VLC. Muszą one być aktualne i proste w nawigacji oraz zrozumiałe i zrozumiałe na co najmniej pięć głównych języków.

Mentorzy: Jean-Baptiste, Alex, Simon

ANALIZA

Wspólnie z Jean-Baptiste rozmawialiśmy o nowym środowisku, do którego zostanie przeniesiona bieżąca dokumentacja użytkownika w celu ulepszenia. Udostępnił on 2 linki prowadzące do repozytorium GitLab pliku źródłowego napisanego we współpracy ze Sfinksem oraz głównej dokumentacji w Read the Docs. Mówi, że nowa dokumentacja jest podobna do tej. Dużo zbierałam informacje na temat tych narzędzi, aby lepiej zrozumieć, jak działają.

Sfinks

Sphinx jest solidnym i dojrzałym rozwiązaniem dla dokumentacji oprogramowania. Oferuje ona wiele funkcji, których oczekują autorzy, np. publikowanie z jednego źródła, ponowne wykorzystanie treści, warunkowanie uwzględnia typ i tagi treści, wiele motywów HTML przeznaczonych dla użytkowników urządzeń mobilnych i komputerów, odwoływania się do stron, dokumentów i projektów. Obsługa indeksu i słowniczek oraz obsługi internacjonalizacji. Wykorzystuje również język znaczników reStructuredText, a wiele jego mocnych stron wynika z możliwości i prostości tej funkcji oraz możliwości tłumaczenia dokumentacji.

Przeczytaj dokumenty

Zapoznaj się z Dokumentami, aby uprościć dokumentację oprogramowania dzięki automatyzacji tworzenia, obsługi wersji i hostowania dokumentów. Wszystko to zawsze jest zsynchronizowane. Oznacza to, że za każdym razem, gdy przekażesz kod do swojego ulubionego systemu kontroli wersji, np. Git, Mercurial, Bazaar lub Subversion, aplikacja Read the Docs automatycznie stworzy Twoje dokumenty, aby Twój kod i dokumentacja były zawsze aktualne. Ma wiele wersji; funkcja Czytaj dokumenty może hostować i tworzyć wiele wersji dokumentów, więc posiadanie dokumentów w wersji 1.0 i 2.0 jest tak łatwe, jak używanie osobnej gałęzi lub tagu w systemie kontroli wersji. Aplikacja Read the Docs jest bezpłatna,typu open source i zawiera dokumentację niemal 100 000 dużych i małych projektów open source w niemal każdym języku ludzkim i komputerowym.

WERYFIKACJA

Sphinx to niezwykle zaawansowane narzędzie, a funkcja Read the Docs wzbogaciła się o hosting w dokumentacji usługi Sphinx, dzięki czemu dokumenty są aktualizowane w różnych wersjach. Razem stanowią wspaniałe narzędzia, z których deweloperzy i twórcy treści technicznych mogą korzystać do tworzenia dokumentacji dla użytkowników dostosowanych do ich potrzeb.

Sfinx umożliwia tłumaczenie dokumentacji na wiele języków. Obsługuje kontrolę wersji, która będzie używana do zarządzania dokumentacją. W przeciwieństwie do obecnej strony wiki, gdzie każdy może edytować bez dodawania właściwych informacji, ten system kontroli wersji zagwarantowałby, że wszystkie zmiany zostaną najpierw sprawdzone, zanim zostaną scalone z repozytorium głównym. Kontrola wersji zwiększy również udział w projekcie w modelu open source, ponieważ użytkownicy mogą tworzyć problemy, otwierać żądania pull itp. Sphinx i czytać Dokumenty, korzystają z aplikacji i sposobów społeczności, takich jak ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin,Write the Docs itp. Jest to doskonałe narzędzie do tworzenia nowej dokumentacji użytkownika VLC.

Oprócz zapoznania się z informacjami o tych narzędziach, przygotowałem także podstawową próbkę. Oto link: https://gitlab.com/Didicodes/demo-vlc-user-documentation do mojego repozytorium Gitlab. Wersja hostowana w pliku readthedocs jest dostępna tutaj: [https://vlc-user-document-demo.readthedocs.io/en/latest/](https://vlc-user-document-demo.readthedocs.io/en/latest/).

STRUKTURA PROPONOWANEJ DOKUMENTACJI

Udało mi się utworzyć strukturę dokumentacji użytkownika VLC, którą można znaleźć tutaj: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Zanim zaczniemy wdrażać tę nową strukturę, musi ona zostać zatwierdzona przez mentorów. Oznacza to, że struktura może się zmienić po sprawdzeniu przez mentorów.

CELE PROJEKTU

  • Zmień strukturę dokumentacji.
  • Zaktualizuj dokumentację, aby dopasować ją do nowoczesnych wersji VLC.
  • Przeprowadź migrację dokumentacji użytkownika do Gitlab przy użyciu Sphinx i ReadtheDokumentacja.
  • Usuń przestarzałe obrazy i informacje.
  • Przeredaguj dokumentację użytkownika tak, aby była bardziej zrozumiała.
  • Skonfiguruj go do tłumaczenia przy użyciu internacjonalizacji Sphinxa.
  • Zaangażuj społeczność zajmującą się dokumentacją, aby użytkownicy mogli zgłaszać i rozwiązywać wszelkie problemy, które napotkali podczas czytania dokumentacji.

DLACZEGO TEN PROJEKT?

Zawsze uważałem, że pisanie kodu, rozwiązywanie problemów i tworzenie oprogramowania osiąga pełnię swoich możliwości, gdy jest się w stanie przekazać innym wiedzę na ten temat. Zawsze fascynowały mnie wysiłki podejmowane przez społeczność VideoLAN w celu tworzenia bezpłatnych rozwiązań multimedialnych. W dzieciństwie VLC zawsze było oprogramowaniem, którego używam do słuchania muzyki i oglądania filmów, bo był bardzo głośny i ma wiele funkcji. To będzie zaszczyt współpracować ze społecznością, która przyczyniła się do tego, by moje dzieciństwo było wspaniałym miejscem.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO TEGO PROJEKTU

Uważam, że jestem odpowiednią osobą do tego projektu, ponieważ:

  • Mam doświadczenie w ulepszaniu dokumentacji organizacji i potrafię używać dowolnego systemu kontroli wersji, więc wykonywanie poleceń na Gitab nie będzie problemem. Co więcej, motywuje mnie do pracy nad projektami, które są wartościowe dla ludzi.
  • Uważam, że jeśli chcesz, by ktoś zrobił coś w najefektywniejszy sposób, musisz to udokumentować. Dokumentując swoje procesy, zapewniasz wydajność, spójność i spokój ducha dla wszystkich zaangażowanych osób.
  • Znam potrzeby użytkowników VLC, ponieważ jestem jednym z nich. Umożliwi to opracowanie dokumentacji w taki sposób, aby wszyscy użytkownicy na całym świecie mogli od razu zrozumieć treść.