Ta strona została przetłumaczona przez Cloud Translation API.

Projekt VideoLAN

Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.

Podsumowanie projektu

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

Opis projektu

ZWROT

Dokumentacja użytkownika ma pomóc w korzystaniu z produktu lub usługi. 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 najczęstszych problemów z oprogramowaniem. Obniżenie kosztów pomocy pozwala też obniżyć koszty pomocy i jest częścią tożsamości korporacyjnej usługi – dobra dokumentacja użytkownika jest oznaką stanu usługi i zespołu programistów.

Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak wykonywać te czynności w sposób skuteczny i wydajny. Dokumentacja użytkownika może odegrać kluczową rolę w zapewnieniu sukcesu usługi, ponieważ wspaniała komunikacja zawsze jest podstawą każdej firmy i usługi. Doskonała dokumentacja pozwala z łatwością skonstruować strukturę, w której każdy może odnieść sukces.

W momencie tworzenia tego dokumentu dokumentacja użytkownika VLC była odczytywana 4 634 065 razy, a odtwarzacz multimedialny VLC jest pobierany ze strony głównej około 23 milionów razy miesięcznie. Oznacza to,że wiele osób na całym świecie używa tego odtwarzacza i może chcieć przeczytać jego dokumentację,aby dowiedzieć się, jak go używać. Dokumentacja użytkownika odtwarzacza multimediów VLC jest jednak obecnie nieaktualna i niekompletna (ostatnia modyfikacja miała miejsce 28 października 2015 r.), a społeczność VideoLAN chce wykorzystać ten projekt do ulepszenia dokumentacji, dzięki której użytkownicy będą mogli płynnie korzystać z tego odtwarzacza.

STAN OBECNY

Dokumentacja użytkownika jest obecnie dostępna na stronie wiki. Są nieaktualne, niepełne, trudno się w nich poruszać lub je znaleźć, nie zawierają informacji o bieżącej wersji odtwarzacza i mogą być przetłumaczone tylko na język niemiecki, co jest uciążliwe dla osób nie znających języka angielskiego.

DLACZEGO PROPONOWANA DOKUMENTACJA UŻYTKOWNIKÓW JEST Ulepszeniem w porównaniu z bieżącą?

Opracowana struktura ma na celu poprawę wyników, spójności i spokoju użytkownika. Będzie on zawierać pisemne przewodniki i związane z nimi obrazy oraz instrukcje i objaśnienia dotyczące korzystania z poszczególnych funkcji odtwarzacza VLC. Będą one aktualne, łatwe w nawigacji, 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żytkowników w celu ulepszenia. Udostępnił on 2 linki prowadzące do repozytorium GitLab pliku źródłowego napisanego dla Sfinksa oraz głównej dokumentacji przechowywanej w sekcji Read the Dokumenty. Mówi, że nowa dokumentacja powinna być podobna do tej. Dużo inwestowałem(-am) w te narzędzia, żeby lepiej zrozumieć, jak one działają.

Sfinks

Sphinx jest zaawansowanym i zaawansowanym rozwiązaniem do obsługi dokumentacji oprogramowania. Zawiera on szereg funkcji, których oczekują autorzy, np. publikowanie w jednym źródle, ponowne wykorzystanie treści, uwzględnianie warunkowe oparte na typie treści i tagach, wiele motywów HTML dla dorosłych, które zapewniają wygodę użytkownikom urządzeń mobilnych i komputerów, oraz obsługę indeksu i słownika oraz obsługi internacjonalizacji. Wykorzystuje też język reStructuredText, a wiele z nich wynika z możliwości i przystępności tej technologii oraz możliwości tłumaczenia dokumentacji.

Przeczytaj dokumenty

Przeczytaj Dokumenty, aby uprościć dokumentację oprogramowania dzięki automatyzacji tworzenia, obsługi wersji i hostingu dokumentów. Oprogramowanie nigdy nie przestaje być zsynchronizowane. Oznacza to, że gdy przekażesz kod do swojego ulubionego systemu kontroli wersji, takiego jak Git, Mercurial, Bazaar czy Subversion, aplikacja Read the Dokumenty automatycznie utworzy Twoje dokumenty, aby Twój kod i dokumentacja były zawsze aktualne. Ma wiele wersji; funkcja Czytaj w Dokumentach umożliwia przechowywanie i tworzenie wielu wersji dokumentów, więc posiadanie dokumentów w wersji 1.0 i 2.0 jest tak proste, jak utworzenie oddzielnej gałęzi lub osobnego tagu w systemie kontroli wersji. Read the Document jest bezpłatnym oprogramowaniem typu open source. Zawiera on dokumentację niemal 100 000 dużych i małych projektów open source w niemal każdym języku ludzkim i komputerowym.

WYŚLIJ

Sphinx to niezwykle zaawansowane narzędzie, a funkcja Read the Dokumenty wzbogaca się o usługę hostowania dokumentacji Sphinx, która pozwala na aktualizację dokumentów w różnych wersjach. Razem tworzy wspaniałe narzędzia, dzięki którym programiści i twórcy techniczni mogą tworzyć dokumentację dla użytkowników najlepiej przydatną dla użytkowników końcowych.

Sfinx umożliwia tłumaczenie dokumentacji na wiele języków. Obsługuje on kontrolę wersji, która będzie wykorzystywana do zarządzania dokumentacją. W przeciwieństwie do obecnej witryny wiki, gdzie każdy może edytować dane bez dodawania odpowiednich informacji, ten system kontroli wersji gwarantuje, że wszystkie zmiany zostaną najpierw scalone z repozytorium głównym. Kontrola wersji zwiększy też udział w projekcie w modelu open source, ponieważ użytkownicy mogą tworzyć problemy, otwierać żądania pull itp. Sfinx i czytać Dokumenty są używane przez listę innych znanych i popularnych społeczności, takich jak ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Create the Dokumenty itd. Jest to świetne narzędzie do wykorzystania w nowej dokumentacji użytkownika VLC.

Nie tylko przeczytałem(am) o tych narzędziach, ale przygotowałem też podstawowy przykład. Oto link: https://gitlab.com/Didicodes/demo-vlc-user-documentation do mojego repozytorium Gitlab, a jego wersję hostowaną w readthedocs znajdziesz tutaj: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/).

STRUKTURA PROPONOWANEJ DOKUMENTACJI

Mam utworzoną strukturę dokumentacji użytkownika VLC, którą można znaleźć tutaj: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Nowa struktura musi zostać zatwierdzona przez mentorów, zanim zostanie wprowadzona. Oznacza to, że struktura może się zmienić, gdy zostanie sprawdzona 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ń nieaktualne obrazy i informacje.
Przeredaguj dokumentację dla użytkowników w taki sposób, aby była bardziej zrozumiała.
Skonfiguruj go do tłumaczenia za pomocą internacjonalizacji Sfinksa.
Zadbaj o to, aby społeczność dokumentalna była zaangażowana w procesy, tak aby użytkownicy mogli zgłaszać i rozwiązywać wszelkie problemy napotkane podczas czytania dokumentacji.

DLACZEGO TEN PROJEKT?

Zawsze byłem przekonany, że pisanie kodu, rozwiązywanie problemów i tworzenie oprogramowania osiąga pełny potencjał, gdy można jednocześnie dowiedzieć się o nim innych ludzi przez pisanie. Zawsze fascynowały mnie wysiłki podejmowane przez społeczność VideoLAN przy tworzeniu bezpłatnego oprogramowania do obsługi multimediów. W dzieciństwie VLC zawsze służyło mi do słuchania muzyki i oglądania filmów, ponieważ był bardzo głośny i miał wiele funkcji. Współpraca ze społecznością, która przyczyniła się do tego, że moje dzieciństwo było wspaniałym doświadczeniem, to był zaszczyt.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DLA TEGO PROJEKTU

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

Mam doświadczenie w ulepszaniu dokumentacji organizacji i mogę 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, aby ktoś zrobił coś w najbardziej efektywny sposób, musisz to udokumentować. Dokumentując swoje procesy, zapewniasz wydajność, spójność i spokój ducha dla wszystkich uczestników.
Znam potrzeby użytkowników VLC, bo jestem jednym z nich. Dzięki temu będziesz tworzyć dokumenty w taki sposób, aby wszyscy użytkownicy na całym świecie mogli je szybko zrozumieć.