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

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
Specjalista ds. technicznych:: Avii
Nazwa projektu:: Utwórz dokumentację użytkownika VLC dotyczącą 1 portu mobilnego (Android)
Długość projektu:: Standardowa długość (3 miesiące)

Opis projektu

ABSTRACT

Dokumentacja użytkownika jest używana jako statyczny system pomocy dla użytkowników końcowych. Zawiera informacje techniczne i nietechniczne o produkcie lub usłudze. pomagają użytkownikom nauczyć się korzystania z oprogramowania lub usługi; Nie każda osoba chce skontaktować się z zespołem pomocy lub zaczekać na e-maila z odpowiedzią, jeśli wystarczy drobna wskazówka, porada lub trik. Dokumentacja użytkownika właśnie to robi. Pozwala też ograniczyć koszty obsługi i jest potwierdzeniem, że produkt i zespół deweloperów są w porządku.

Aplikacja VLC na Androida została pobrana ponad 100 milionów razy tylko ze Sklepu Google Play. VLC oferuje wiele funkcji dla portów mobilnych, od odtwarzania dźwięku i obrazu po strumieniowanie sieciowe. Często użytkownicy chcą korzystać z tych wspaniałych funkcji, ale nie mogą tego zrobić. Wyszukiwanie bloga lub losowego filmu wymaga dużo czasu i cierpliwości, a także nie daje pewności, że uzyskane informacje są autentyczne. Obecnie VLC udostępnia dokumentację dla użytkowników VLC na Androida na stronie wiki, a opisy tych funkcji są w niej niepełne lub ich brak. Ponadto strony wiki zostały ostatnio zaktualizowane w marcu 2019 r. Obecny projekt zapewni nową dokumentację użytkownika z nowoczesnym wyglądem i większą łatwością obsługi portu na Androida.

AKTUALNA SYTUACJA

Strony w Wiki są całkowicie nieaktualne i zawierają bardzo mało informacji o najnowszej wersji VLC. Nie są też łatwe w nawigacji. Nie ma widocznej opcji czytania dokumentacji w języku innym niż angielski. Nie zawiera ona żadnych opisów funkcji.

ANALIZA

-> Obecna dokumentacja jest już nieaktualna i musi zostać napisana w nowy sposób, z użyciem innej platformy i innych narzędzi.

-> Większość użytkowników Androida ma niewielką lub żadną wiedzę techniczną. Są jednak osoby, które potrzebują bardziej szczegółowych informacji technicznych na temat danej funkcji. Tworzenie i utrzymywanie 2 osobnych dokumentacji na potrzeby każdego z wymienionych wyżej celów nie jest dobrym pomysłem. Nawet w ramach tej samej dokumentacji podział funkcji na techniczne i nietechniczne może wprowadzać dodatkowe zamieszanie. Większość użytkowników jest przyzwyczajona do interfejsu i funkcji, z których korzysta, dlatego nie każdy może łatwo zdecydować, czy ma do czynienia z obsługą techniczną czy nietechniczną. Chcielibyśmy uprościć im to zadanie.

-> Większość użytkowników będzie szukać informacji na smartfonie i odpoczywać na komputerze lub innym urządzeniu. Dokumentacja powinna więc dać się łatwo dostosować do każdego rozmiaru ekranu. Nie powinno też wprowadzać żadnych nieporozumień w nawigacji.

-> Nie wszystkie funkcje wersji na komputery są dostępne w wersji na Androida, a nawet jeśli są dostępne, nie działają tak samo na obu platformach. Wynika to z faktu, że aplikacja komputerowa jest rozwijana znacznie dłużej i osiągnęła swego rodzaju nasycenie. Natomiast port dla telefonów komórkowych jest stosunkowo nowy i wciąż się rozwija. Poza tym, choć obecnie urządzenia mobilne stają się coraz bardziej wydajne, istnieją oczywiste ograniczenia dotyczące rodzaju funkcji, które możemy wdrożyć, głównie ze względu na wymagania użytkowników. Funkcja, której nikt nie używa, to marnotrawienie zasobów na rozwój. Dlatego nie zalecamy czytania obu dokumentów na podstawie funkcji.

NA PODSTAWIE WYŻEJ ANALIZY PROPONUJEMY NASTĘPUJĄCE. 1. Obecnie dokumentacja dla użytkowników komputerów korzysta z generatora dokumentacji Sphinx i motywu Read the Docs. Korzystanie z tego samego identyfikatora w przypadku portu Androida pomoże nam na następujących etapach: -> Łatwe scalanie obu dokumentów. -> Jest zoptymalizowana pod kątem wszystkich rozmiarów ekranu. -> Płynne przechodzenie do dokumentacji użytkownika Androida z dokumentacji na komputery

oddzielanie rozdziałów, sekcji i podrozdziałów zgodnie z ich względną pozycją w aplikacji; Na przykład tryb w tle lub PiP znajduje się w menu Więcej > Ustawienia > Wideo, więc struktura rozdziałów będzie taka:

Więcej

|__Ustawienia

| |__Biblioteka multimediów

| |__Video -->Background/PiP Mode

: -> Dzięki temu użytkownicy będą mogli łatwo przejść do części, w której potrzebują pomocy, porównując ją z względną lokalizacją w aplikacji. W przypadku każdej funkcji możemy dodatkowo oddzielić części techniczne od nietechnicznych. Najpierw napiszemy prosty opis nietechniczny, a następnie podświetlimy lub oznaczymy techniczne części tej samej funkcji (jeśli takie istnieją). Może to wymagać pewnego powtórzenia, ale powinno zapewnić bezproblemowe działanie większości użytkowników bez wiedzy technicznej. Pomoże to też w przyszłości, ponieważ zwiększy łatwość konserwacji. Ponieważ aplikacja osiągnie stan nasycenia, względny interfejs użytkownika prawdopodobnie się nie zmieni. W przyszłości, jeśli zostanie dodana/usunięta nowa funkcja, możemy po prostu refaktoryzować tę sekcję. Jeśli zmieni się cały interfejs, możemy zmienić kolejność sekcji lub rozdziałów albo zmienić strukturę całego dokumentu. W obu przypadkach musimy zmodyfikować całą dokumentację, ponieważ zrzuty ekranu trzeba będzie zastąpić, aby pasowały do obecnego interfejsu. Demo wersji roboczej jest dostępne tutaj : https://avinal.gitlab.io/vlc-android-docs/
Każda sekcja dokumentacji powinna zawierać etykietowany zrzut ekranu , opis funkcji, bardziej techniczną część (jeśli taka istnieje) oraz porady i wskazówki dotyczące tej funkcji.

-> Samodzielne opracowanie tej dokumentacji na komputery pozwoli nam połączyć obie dokumentacje w zaledwie kilka kroków, bez wpływu na bieżącą dokumentację i bez konieczności wprowadzania zmian w jej treści. Proponuję umieścić całą tę dokumentację w sekcji dotyczącej Androida w dokumentacji na komputery, gdy tylko zostanie ona opracowana, a następnie utworzyć link stały do dokumentacji VLC na Androida.

-> Dalsze ulepszenia mogą obejmować zmianę strony startowej w dokumentacji dla użytkowników komputerów, tak aby użytkownicy mogli bezpośrednio wybrać ulubiony system operacyjny, a następnie przekierować go do jego dokumentacji. Dokumentacja użytkownika VLC dla Windows, macOS i Linux jest już dobrze zaprojektowana i przetłumaczona, dlatego możemy udostępnić opcje Windows/MacOS/Linux lub Android/iOS. Pozwoli to utworzyć przejrzystą, ujednoliconą dokumentację użytkownika z 1 linkiem do wszystkich portów.

DLACZEGO MOJE PROPONOWANE DOKUMENTACJE UŻYTKOWNIKA SĄ LEPSZE? Ta propozycja dokumentacji użytkownika jest uporządkowana na podstawie typowych wzorców, których używa użytkownik, aby uzyskać pomoc. Dokumentacja zawiera wszystkie wymagane funkcje, takie jak prostota, przejrzystość, wygląd i wrażenia, a także informacje o technologii, aby zmaksymalizować łatwość użytkowania i wygodę użytkowników. Jest to też łatwe do utrzymania, ponieważ nie trzeba już utrzymywać dokumentacji dotyczącej poszczególnych użytkowników dla każdego portu.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO TEGO PROJEKTU? -> Piszę kody od 2 lat i często muszę zapoznać się z dokumentacją interfejsu API dla określonych bibliotek lub oprogramowania, a nawet udokumentować własny kod. Wiem dokładnie, czego użytkownicy oczekują od dokumentacji, z jakimi problemami się borykają i jak szukają pomocy. Muszę mieć możliwość zastosowania tych samych doświadczeń do napisania spójnej i łatwo czytelnej dokumentacji.

-> Pisałem już sporo treści technicznych na Quora, Stack Overflow i na różnych innych platformach. Wiem, jak wyjaśniać rzeczy w sposób przyciągający uwagę i zrozumiały dla odbiorców.

-> VLC na Androida to potężne i bardzo znane narzędzie, ale większość jego funkcji jest nieznana lub nie ma do niej pomocy. Od wielu lat używam VLC na komputerach i urządzeniach mobilnych, więc wiem, z jakimi problemami może się spotkać użytkownik. Wykorzystując całą swoją wiedzę i doświadczenie, mogę zapewnić Ci świetną dokumentację.