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

Projekt VLC

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:: VLC
Pisarz techniczny:: Awii
Nazwa projektu:: Utwórz dokumentację użytkownika VLC dla jednego portu mobilnego (Android)
Długość projektu:: Standardowa długość (3 miesiące)

Opis projektu

ZWROT

Dokumentacja użytkownika jest wykorzystywana jako statyczny system wsparcia dla użytkowników końcowych. Zawiera on informacje techniczne oraz nietechniczne dotyczące produktu lub usługi. Pomaga użytkownikom nauczyć się korzystać z oprogramowania lub usług. Nie każda osoba chce kontaktować się z zespołem pomocy lub czekać na e-maila z odpowiedzią, jeśli potrzebuje jedynie wskazówek, porad lub wskazówek. Właśnie do tego służy dokumentacja użytkownika. Obniża też koszty pomocy i pozwala potwierdzić stan produktu oraz zespół programistów.

Aplikacja VLC na Androida została pobrana ponad 100 milionów razy ze Sklepu Google Play. VLC udostępnia na portach mobilnych wiele funkcji, takich jak odtwarzanie audio-wideo po strumieniowanie z sieci. Ludzie często chcą korzystać z tych świetnych funkcji, ale im się to nie udaje. Wyszukiwanie w tym celu bloga lub losowego filmu wymaga dużo czasu i cierpliwości, a mimo to uzyskane informacje nie są autentyczne. Obecnie VLC hostuje dokumentację użytkowników VLC na Androida na stronie wiki i zawiera mniej opisów tych funkcji lub nie zawiera ich wcale. Oprócz tego w marcu 2019 r. zaktualizowaliśmy strony wiki. W ramach bieżącego projektu nowa dokumentacja użytkownika będzie miała nowoczesny wygląd i będzie łatwiejsza w obsłudze portu Androida.

OBECNA SYTUACJA

Strony wiki są całkowicie nieaktualne i zawierają niewiele informacji o najnowszej wersji VLC. Ponadto nie jest ona łatwa w obsłudze. Nie ma opcji pozwalającej przeczytać dokumentację w języku innym niż angielski. Nie zawiera on żadnych opisów cech.

ANALIZA

-> Obecnie bieżąca dokumentacja jest nieaktualna i musi zostać napisana w nowy sposób i przy użyciu innej platformy oraz narzędzi.

-> Większość użytkowników Androida ma niewielką wiedzę techniczną lub nie ma jej wcale. Są jednak osoby, które potrzebują bardziej technicznych informacji o danej funkcji. Napisanie i utrzymywanie dwóch oddzielnych dokumentów do każdego z powyższych celów nie jest dobrym pomysłem. Z kolei nawet w tej samej dokumentacji dzielenie funkcji ze względu na kwestie techniczne i nietechniczne powoduje dodatkowe niejasności. Ponieważ większość użytkowników jest przyzwyczajona do interfejsu i funkcji, z których korzysta, każdy użytkownik może mieć problem z rozwiązaniem decyzji o kwestiach technicznych czy nietechnicznych. Dlatego chcemy uprościć im proces.

-> Większość użytkowników próbuje uzyskać informacje bezpośrednio na smartfonie, a odpoczywać na komputerze i innych urządzeniach. Dokumentacja powinna być więc łatwa do dostosowania do każdego rozmiaru ekranu. Nie chcę wprowadzać w błąd nawigacji.

-> Nie każda funkcja wersji komputerowej jest dostępna na porcie Androida i jeśli jest dostępna, nie działa tak samo na obu portach. Wynika to z faktu, że aplikacje na komputery są opracowywane od dłuższego czasu i osiągnęły już pewnego poziomu nasycenia, natomiast port komórkowy jest stosunkowo nowy i nadal się rozwija. Poza tym chociaż obecnie urządzenia mobilne stają się tak wydajne, istnieją oczywiste ograniczenia dotyczące typów funkcji, które możemy włączyć głównie ze względu na zapotrzebowanie ze strony użytkowników. Funkcja, której nikt nie używa, to strata zasobów programistycznych. Z tego względu nie zalecamy przedstawiania obu dokumentów w oparciu o funkcje.

NA PODSTAWIE POWYŻEJ ANALIZY PROPONOWAM NASTĘPUJĄCE INFORMACJE. 1. Obecnie w dokumentacji dla użytkowników wersji na komputery jest wykorzystywany generator dokumentacji Sphinx oraz motyw Czytaj dokumenty. Wykorzystanie tych samych informacji w przypadku portu Androida pomoże nam na kilka sposobów: -> Łatwe połączenie dokumentacji. -> Jest zoptymalizowana pod kątem wszystkich rozmiarów ekranu. -> Sprawne działanie po przejściu do dokumentacji użytkownika Androida w dokumentacji na komputerze.

podział rozdziałów, sekcji i podsekcji według ich względnego umiejscowienia w aplikacji; Na przykład: Tryb Tło/PiP znajduje się w sekcji Więcej -> Ustawienia -> Wideo, więc struktura rozdziałów będzie

Więcej

|__Ustawienia

| |__Biblioteka multimediów

| |__Video --> Tło/Tryb PIP

: -> To podejście ułatwi dostęp do danych, ponieważ użytkownicy będą mogli łatwo przejść do miejsca, w którym potrzebują pomocy, porównując je ze względnym położeniem w aplikacji. W przypadku każdej z tych funkcji możemy dodatkowo podzielić aspekty techniczne i nietechniczne. Najpierw napiszemy prosty opis, który nie jest techniczny, a następnie podświetlimy i oznaczymy elementy techniczne tej samej funkcji, jeśli występują. Może się to wiązać z pewnymi powtórzeniami, ale pozwoli bezproblemowo odbić się większości osób o innych umiejętnościach technicznych. Pomoże to także w przyszłości, poprawiając łatwość obsługi. Gdy aplikacja osiągnie stan nasycenia, względny interfejs użytkownika prawdopodobnie nie zmieni się zbytnio w przyszłości, więc jeśli w przyszłości dodamy lub usuniemy nową funkcję, możemy po prostu zmodernizować tę sekcję. Jeśli cały interfejs użytkownika ulegnie zmianie, możemy rozmieścić sekcje/rozdziały lub zmienić strukturę całego dokumentu. W każdym przypadku musimy zmodyfikować całą dokumentację, ponieważ zrzut ekranu musi zostać zastąpiony, aby pasował do bieżącego interfejsu. Działająca wersja demonstracyjna znajduje się tutaj : https://avinal.gitlab.io/vlc-android-docs/
Każda sekcja dokumentacji powinna zawierać zrzut ekranu opatrzony etykietą , opis funkcji, część techniczną (jeśli jest dostępna) oraz wskazówki i porady dotyczące danej funkcji.

-> Jeśli samodzielnie opracowujesz tę dokumentację dla użytkowników na komputerze, ułatwisz nam scalenie obu dokumentów w zaledwie kilku krokach. Nie będzie to miało wpływu na bieżącą dokumentację ani nie będzie mieć na nią wpływu w trakcie tworzenia aplikacji. Proponuję umieścić całą tę dokumentację w sekcji dotyczącej Androida w dokumentacji dla komputerów, a potem utworzyć link bezpośredni do dokumentacji VLC dla Androida.

-> Dodatkowe ulepszenia mogą obejmować zmodyfikowanie strony startowej w dokumentacji dla użytkowników komputerów, co umożliwia bezpośredni wybór ulubionego systemu operacyjnego oraz przekierowanie do jego dokumentacji. Ponieważ dokumentacja VLC dla systemów Windows, macOS i Linux jest już dobrze opracowana i przekształcona, możemy dodać opcje do wyboru: Windows/macOS/Linux lub Android lub iOS. Spowoduje to utworzenie przejrzystej, ale ujednoliconej dokumentacji użytkownika z 1 linkiem do wykorzystania we wszystkich portach.

DLACZEGO MOJA PROPONOWANA DOKUMENTACJA UŻYTKOWNIKÓW JEST LEPSZA? Struktura tej dokumentacji opiera się na typowych wzorcach, z których użytkownicy korzystają w celu uzyskania pomocy. Dokumentacja łączy wszystkie wymagane funkcje, takie jak prostota, przejrzystość, wygląd i styl, wiedza technologiczna, aby zmaksymalizować łatwość obsługi i wygodę użytkowników. Łatwo to też obsługiwać, ponieważ nie trzeba już tworzyć dokumentacji poszczególnych użytkowników przy każdym przenoszeniu danych.

DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DLA TEGO PROJEKTU? -> Piszę kody od 2 lat i często muszę przejrzeć dokumentację interfejsu API niektórych bibliotek lub oprogramowania, a nawet udokumentować własny kod. Wiem dokładnie, czego ludzie szukają w dokumentacji, jakie mają problemy i jak postępują, aby uzyskać pomoc. Będę mógł wykorzystać ten sam mechanizm, aby stworzyć spójną i czytelną dokumentację.

-> Piszę aktywnie w sprawach technicznych na platformach Quora, Stack Overflow i na różnych innych platformach. Wiem, jak wyjaśniać pewne rzeczy w chwytliwy i zrozumiały sposób.

-> VLC na Androida to zaawansowane i słynne narzędzie, ale większość jego funkcji jest nieznana lub nie ma pomocy. Od wielu lat używam VLC zarówno na komputerach, jak i na urządzeniach mobilnych, i wiem, jakie problemy mogą napotykać użytkownicy. Dzięki swojej wiedzy i doświadczeniu mogę zapewnić doskonałą dokumentację.