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
- VideoLAN
- Pisarz techniczny:
- Edidiong Anny Asikpo
- Nazwa projektu:
- Zmodernizuj (napisz na nowo) dokumentację użytkownika VLC
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
ABSTRACT
Dokumentacja użytkownika ma ułatwić użytkownikom korzystanie z produktu lub usługi. Dobra dokumentacja użytkownika jest bardzo ważna, ponieważ zapewnia użytkownikom możliwość nauczenia się, jak korzystać z oprogramowania, jego funkcji, porad i wskazówek, a także rozwiązywania typowych problemów, które pojawiają się podczas korzystania z oprogramowania. Obniża też koszty obsługi klienta i stanowi element tożsamości korporacyjnej produktu: dobra dokumentacja użytkownika jest oznaką jakości produktu i zespołu programistów.
Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i wydajnie wykonywać te czynności. Dokumentacja użytkownika może odgrywać kluczową rolę w zapewnieniu sukcesu produktu, ponieważ skuteczna komunikacja zawsze będzie podstawą każdej firmy lub produktu. Dobra dokumentacja to nic innego jak komunikacja w ramach łatwego w obsłudze systemu, do którego każdy może mieć dostęp.
W momencie pisania tego tekstu dokumentacja użytkownika VLC została wyświetlona 4 634 065 razy, a VLC Media Player jest pobierany z głównej strony internetowej około 23 milionów razy miesięcznie. Pokazuje to,że wiele osób na całym świecie korzysta z odtwarzacza VLC Media Player i może chcieć przeczytać jego dokumentację użytkownika,aby dowiedzieć się, jak z niego korzystać. Dokumentacja użytkownika odtwarzacza VLC jest jednak obecnie nieaktualna i niepełna (ostatnia modyfikacja miała miejsce 28 października 2015 r.), a społeczność VideoLAN chce wykorzystać ten projekt do ulepszenia dokumentacji użytkownika, aby zapewnić użytkownikom końcowym płynne korzystanie z odtwarzacza VLC.
AKTUALNY STAN
Obecnie dokumentacja użytkownika jest dostępna na stronie wiki. Jest on nieaktualny, niekompletny, trudny w nawigacji i znalezieniu informacji, nie zawiera informacji o aktualnej wersji odtwarzacza multimediów i może być tłumaczony tylko na język niemiecki, co stanowi poważną przeszkodę dla osób, które nie znają języka angielskiego.
DLACZEGO PROPONOWANA DOKUMENTACJA UŻYTKOWNIKA JEST ULEPSZENIEM W PORÓWNANIU Z OBECZNĄ?
Proponowana dokumentacja użytkownika zostanie uporządkowana w taki sposób, aby poprawić wydajność, spójność i spokój ducha użytkownika. Będzie zawierać przewodniki w formie tekstu i powiązanych z nimi obrazów, a także instrukcje i wyjaśnienia dotyczące korzystania z każdej funkcji odtwarzacza VLC. Będzie aktualny, łatwy w obsłudze, zrozumiały i przetłumaczalny na co najmniej 5 głównych języków.
Mentorzy: Jean-Baptiste, Alex, Simon
ANALIZA
Jean-Baptiste i ja rozmawialiśmy o nowym środowisku, do którego zostanie przeniesiona obecna dokumentacja użytkownika w celu jej ulepszenia. Jean-Baptiste udostępnił 2 linki do repozytorium Gitlab z plikiem źródłowym napisanym w Sphinxie oraz główną dokumentację hostowaną w Read the Docs. Powiedział, że nowa dokumentacja będzie podobna. Poczytałem o tych narzędziach dużo, żeby lepiej zrozumieć ich działanie.
Sfinks
Sphinx to solidne i dojrzałe rozwiązanie do dokumentacji oprogramowania. Zawiera ono wiele funkcji, których oczekują twórcy, takich jak publikowanie z jednego źródła, ponowne wykorzystanie treści za pomocą include, include warunkowe na podstawie typu treści i tagów, wiele dojrzałych motywów HTML, które zapewniają użytkownikom wygodę na urządzeniach mobilnych i komputerach, odwołania do stron, dokumentów i projektów, obsługa indeksu i glosariusza oraz obsługa internacjonalizacji. Jako język znaczników używa też reStructuredText, a wiele jego zalet wynika z mocy i prostoty tego formatu oraz jego zdolności do tłumaczenia dokumentacji.
Przeczytaj dokumentację
Przeczytaj, jak Dokumenty upraszczają dokumentację oprogramowania, automatyzując kompilowanie, obsługę wersji i hostowanie dokumentów za Ciebie. Nigdy nie traci synchronizacji. Oznacza to, że za każdym razem, gdy wypchniesz kod do ulubionego systemu kontroli wersji (czy to Git, Mercurial, Bazaar czy Subversion), Read the Docs automatycznie utworzy dokumenty, dzięki czemu Twój kod i dokumentacja będą zawsze aktualne. Ma wiele wersji. Read the Docs może hostować i tworzyć wiele wersji dokumentów, więc posiadanie wersji 1.0 i 2.0 jest tak proste jak posiadanie osobnej gałęzi lub tagu w systemie kontroli wersji. Read the Docs to bezpłatna platforma z dokumentacją na temat prawie 100 tysięcy dużych i małych projektów open source w prawie wszystkich językach ludzkich i komputerowych.
ZWERYFIKUJ
Sphinx to niezwykle zaawansowane narzędzie, a wbudowana wersja Read the Document zapewnia hosting dokumentacji Sphinx, która umożliwia aktualizowanie dokumentów w różnych wersjach. Stanowią razem wspaniały zestaw narzędzi, których programiści i twórcy treści technicznych mogą używać do tworzenia dokumentacji użytkownika najbardziej odpowiadającej użytkownikom.
Sphinx obsługuje tłumaczenie dokumentacji na różne języki. Obsługuje kontrolę wersji, która służy do zarządzania dokumentacją. W przeciwieństwie do obecnej wiki, w której każdy może edytować i dodawać informacje, ten system kontroli wersji zapewni, że wszystkie zmiany zostaną najpierw sprawdzone, zanim zostaną scalone z głównym repozytorium. Kontrola wersji zwiększy też udział open source w dokumentacji do projektu, ponieważ użytkownicy mogą tworzyć problemy, otwierać pull requesty itp. Sphinx i read the Docs są używane przez inne wspaniałe społeczności, takie jak ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs itp., i są świetnym narzędziem do tworzenia nowej dokumentacji dla użytkowników VLC.
Nie tylko czytałem o tych narzędziach, ale też utworzyłem podstawową próbkę. Oto link: https://gitlab.com/Didicodes/demo-vlc-user-documentation do mojego repozytorium Gitlab. Wersję hostowaną na readthedocs można znaleźć tutaj: [https://vlc-user-documentation-demo.readthedocs.io/pl/latest/](https://vlc-user-documentation-demo.readthedocs.io/pl/latest/.
STRUKTURA PROPONOWANEJ DOKUMENTACJI
Utworzyłem strukturę dokumentacji użytkownika VLC, którą można znaleźć tutaj: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Zanim rozpocznie się wdrażanie nowej struktury, musi ona zostać zatwierdzona przez mentorów. Oznacza to, że struktura może ulec zmianie po sprawdzeniu przez mentorów.
CELE PROJEKTU
- Zmień strukturę dokumentacji.
- zaktualizować dokumentację, aby pasowała do nowszych wersji VLC;
- Przeniesienie dokumentacji dla użytkowników do Gitlaba za pomocą Sphinxa i ReadtheDocs.
- Usuń nieaktualne obrazy i informacje.
- Zmodyfikuj dokumentację użytkownika, aby była bardziej zrozumiała.
- Skonfiguruj go do tłumaczenia za pomocą Sphinx Internationalization.
- Utwórz dokumentację, którą użytkownicy będą mogli rozwijać, aby mogli zgłaszać problemy lub rozwiązywać je podczas czytania dokumentacji.
DLACZEGO TEN PROJEKT?
Zawsze byłam przekonana, że pisanie kodu, rozwiązywanie problemów i tworzenie oprogramowania osiąga swój pełny potencjał, gdy masz też możliwość poinformowania innych o swoich osiągnięciach. Osobiście zawsze fascynowały mnie wysiłki podejmowane przez społeczność VideoLAN w zakresie tworzenia bezpłatnych rozwiązań programowych do multimediów. Gdy byłam dzieckiem, odtwarzacz VLC Media Player był zawsze oprogramowaniem, którego używałam do słuchania muzyki lub oglądania filmów, ponieważ był bardzo głośny i zawierał mnóstwo funkcji. To będzie zaszczyt współpracować ze społecznością, która przyczyniła się do tego, żeby moje dzieciństwo było wspaniałe.
DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO REALIZACJI 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ń w Gitab nie będzie problemem. Poza tym praca nad projektami, które przynoszą ludziom korzyści, jest dla mnie bardzo ważna.
- Jeśli chcesz, aby ktoś zrobił coś w jak najbardziej efektywny sposób, musisz to udokumentować. Dokumentując swoje procesy, zapewniasz skuteczność, spójność i spokój ducha dla wszystkich zaangażowanych osób.
- Znam potrzeby użytkowników VLC, ponieważ sam do nich należę. Dzięki temu dokumentacja będzie napisana w taki sposób, aby każdy użytkownik na całym świecie mógł ją zrozumieć od razu.