Progetto VLC

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo del progetto

Organizzazione open source:
VLC
Redattore tecnico:
Avii
Nome del progetto:
Crea la documentazione utente di VLC per una porta mobile (Android)
Durata del progetto:
Durata standard (3 mesi)

Project description

ABSTRACT

La documentazione utente viene utilizzata come sistema di assistenza statico per aiutare gli utenti finali. Fornisce informazioni tecniche e non tecniche su un prodotto o servizio. Aiuta gli utenti a imparare a utilizzare il software o i servizi. Non tutti vogliono contattare l'assistenza o attendere una risposta via email se hanno bisogno solo di qualche indicazione, suggerimento o trucco. La documentazione utente fa proprio questo. Inoltre, riduce i costi di assistenza ed è un indicatore dello stato di salute del prodotto e del team di sviluppatori.

VLC per Android è stato scaricato oltre 100 milioni di volte solo dal Google Play Store. VLC offre molte funzionalità per le sue versioni per dispositivi mobili, dalla riproduzione audio-video allo streaming di rete. Spesso le persone vogliono utilizzare queste fantastiche funzionalità, ma non sono in grado di farlo. Cercare un blog o un video casuale per questo richiede molto tempo e pazienza e, comunque, non c'è alcuna autenticità delle informazioni ottenute. Al momento, VLC ospita la documentazione per gli utenti di VLC per Android nella pagina della wiki e fornisce una descrizione ridotta o nessuna di queste funzionalità. Inoltre, le pagine della wiki sono state aggiornate per l'ultima volta a marzo 2019. Il progetto attuale fornirà una nuova documentazione utente con un design moderno e una maggiore facilità d'uso per la porta Android.

SITUAZIONE ATTUALE

Le pagine della wiki sono completamente obsolete e contengono pochissime informazioni sull'ultima versione di VLC. Inoltre, non sono facili da navigare. Non è visibile un'opzione per leggere la documentazione in un'altra lingua diversa dall'inglese. Non contiene descrizioni delle funzionalità.

ANALISI

-> Al momento la documentazione attuale è obsoleta e deve essere scritta in un modo nuovo e utilizzando una piattaforma e strumenti diversi.

-> La maggior parte degli utenti di Android ha poca o nessuna conoscenza tecnica. Tuttavia, ci sono persone che hanno bisogno di informazioni più tecniche su una funzionalità. Non è una buona idea scrivere e gestire due documentazioni separate per ciascuno dei suddetti scopi. Anche nella stessa documentazione, la suddivisione di una caratteristica in base a caratteristiche tecniche e non tecniche crea ulteriore confusione. Anche in questo caso, la maggior parte degli utenti è abituata all'interfaccia utente che vede o alle funzionalità che utilizza, di conseguenza non è facile per tutti decidere se qualcosa è di natura tecnica o non tecnica. Vogliamo semplificare questa procedura per loro.

-> La maggior parte degli utenti cercherà di ottenere informazioni tramite lo smartphone stesso e il resto tramite computer o altri dispositivi. Pertanto, la documentazione deve essere facilmente adattabile a qualsiasi dimensione dello schermo. e non deve creare confusione sulla navigazione.

-> Non tutte le funzionalità della versione desktop sono disponibili nella porta Android e, se disponibili, non funzionano allo stesso modo in entrambe le porte. Questo perché le applicazioni desktop sono in fase di sviluppo da molto più tempo e hanno raggiunto una sorta di stato di saturazione, mentre la porta mobile è relativamente nuova e ancora in fase di sviluppo. A parte questo, sebbene al giorno d'oggi i dispositivi mobili stiano diventando così potenti, esistono evidenti restrizioni al tipo di funzionalità che possiamo incorporare principalmente a causa della domanda dell'utente finale. Una funzionalità che nessuno utilizza è uno spreco di risorse di sviluppo. Pertanto, non è consigliabile utilizzare entrambe le documentazioni in base alle funzionalità.

IN BASE ALL'ANALISI SOPRA RIPORTATA, PROPONGO QUANTO SEGUE. 1. Al momento, la documentazione per gli utenti di computer utilizza il generatore di documentazione Sphinx e il tema Read the Docs. L'utilizzo della stessa porta per Android ci aiuterà nei seguenti modi: -> Facile unione di entrambe le documentazioni. -> È ottimizzato per tutte le dimensioni dello schermo. -> Esperienza fluida quando si accede alla documentazione per gli utenti Android tramite la documentazione per il desktop

  1. Separazione dei capitoli, delle sezioni e delle sottosezioni in base alla loro posizione relativa nell'applicazione. Ad esempio, la modalità Background/PIP si trova all'interno di Altro -> Impostazioni->Video, quindi la struttura dei capitoli sarà
    Altro
    |__Settings
    | |__Raccolta multimediale
    | |__Video --> Modalità in background/PiP
    : -> Questo approccio migliorerà la facilità di accesso poiché gli utenti saranno in grado di raggiungere facilmente la parte in cui hanno bisogno di aiuto confrontandola con la posizione relativa nell'applicazione. Per ciascuna delle funzionalità possiamo separare ulteriormente le parti tecniche e non tecniche. Dovremo prima scrivere una descrizione semplice e non tecnica, quindi evidenziare o etichettare ulteriormente le parti tecniche della stessa funzionalità, se presenti, appena sotto. Ciò potrebbe comportare alcune ripetizioni, ma garantirà un'esperienza fluida per la maggior parte degli utenti non tecnici. Ciò contribuirà anche a migliorare la manutenibilità in futuro. Poiché l'applicazione raggiungerà lo stato di saturazione, l'interfaccia utente relativa non cambierà molto, quindi in futuro, se viene aggiunta/rimossa una nuova funzionalità, potremo semplicemente eseguire il refactoring della sezione. Se l'intera interfaccia utente viene modificata, possiamo riorganizzare le sezioni/i capitoli o ristrutturare l'intero documento. In entrambi i casi, dobbiamo modificare l'intera documentazione perché gli screenshot dovranno essere sostituiti in modo da corrispondere all'interfaccia utente attuale. Una demo funzionante è ospitata qui : https://avinal.gitlab.io/vlc-android-docs/

  2. Ogni sezione della documentazione deve essere costituita da uno screenshot etichettato , da una descrizione della funzione, da eventuali altre parti tecniche e da suggerimenti utili per la funzione.

-> Sviluppare in modo indipendente questa documentazione dell'utente dal desktop ci aiuterà a unire entrambi i documenti in pochi passaggi senza influire sulla documentazione corrente o essere influenzata dalla stessa durante lo sviluppo. Propongo di inserire tutta questa documentazione nella sezione Android della documentazione per computer una volta sviluppata e poi di creare un permalink per la documentazione di VLC per Android.

-> Altri miglioramenti potrebbero includere la riprogettazione della pagina iniziale della documentazione per gli utenti di computer per consentire agli utenti di scegliere direttamente il sistema operativo preferito e poi reindirizzarli alla documentazione del sistema operativo scelto. Poiché la documentazione utente di VLC per Windows, macOS e Linux è già ben progettata e tradotta, potremmo mettere a disposizione opzioni tra Windows/MacOS/Linux o Android o iOS. Questo comporterà una documentazione utente ben separata ma unificata con un solo link da utilizzare per tutte le porte.

PERCHÉ LA DOCUMENTAZIONE PER GLI UTENTI CHE PROPONGO È MIGLIORE? Questa documentazione utente proposta è strutturata in base ai pattern comuni seguiti dall'utente finale per ricevere assistenza. La documentazione combina tutte le funzionalità richieste, ad esempio semplicità, chiarezza, aspetto e conoscenza tecnologica, per massimizzare la facilità d'uso e l'esperienza utente finale. Inoltre, è facilmente gestibile perché non è più necessario mantenere la documentazione dei singoli utenti per ogni porta.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO? -> Scrivo codice da 2 anni e spesso devo consultare la documentazione dell'API per determinate librerie o per alcuni software o anche per documentare il mio codice. So esattamente cosa vogliono vedere le persone nella documentazione, quali problemi devono affrontare e come si approcciano per ricevere assistenza. Sarò in grado di applicare la stessa esperienza per scrivere una documentazione coerente e facilmente leggibile.

-> Scrivo attivamente contenuti tecnici su Quora, Stack Overflow e altre piattaforme. So spiegare le cose in modo accattivante e comprensibile per le persone.

-> VLC per Android è uno strumento potente e molto famoso, ma la maggior parte delle sue funzionalità sono sconosciute o non sono disponibili assistenza. Utilizzo VLC su piattaforme desktop e mobile da molti anni e so quali problemi può riscontrare un utente. Unendo tutte le mie conoscenze ed esperienze, posso garantirti una documentazione eccezionale.