Questa pagina è stata tradotta dall'API Cloud Translation.

Progetto VLC

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:: VLC
Technical writer:: Avii
Nome progetto:: Crea la documentazione dell'utente VLC per una porta mobile (Android)
Durata del progetto:: Durata standard (3 mesi)

Project description

RIEPILOGO

La documentazione per l'utente viene utilizzata come sistema di supporto statico per assistere gli utenti finali. Fornisce informazioni sia tecniche che non tecniche su un prodotto o servizio. Aiuta gli utenti a imparare a usare software o servizi. Non tutti vogliono contattare l'assistenza o aspettare una risposta via email se ha solo bisogno di indicazioni, suggerimenti o espedienti. La documentazione utente serve proprio per questo. Riduce inoltre i costi di assistenza ed è un'identità dello stato del prodotto e del team di sviluppo.

VLC per Android è stato scaricato oltre 100 milioni di volte solo dal Google Play Store. VLC offre molte funzionalità per le sue porte mobili, dalla riproduzione audio-video allo stream di rete. Spesso le persone desiderano utilizzare queste fantastiche funzioni, ma non sono in grado di farlo. La ricerca di un blog o di un video a caso richiede molto tempo e pazienza; tuttavia, le informazioni ottenute non sono veritiere. Attualmente, VLC ospita la documentazione utente di VLC per Android nella pagina wiki e fornisce una descrizione minore o nulla di queste funzionalità. Inoltre, l'ultimo aggiornamento delle pagine wiki è stato eseguito a marzo 2019. Il progetto attuale fornirà la nuova documentazione per gli utenti con un design moderno e una maggiore facilità d'uso per la porta Android.

SITUAZIONE ATTUALE

Le pagine wiki sono completamente obsolete e contengono molto meno informazioni sull'ultima versione di VLC. Inoltre, non sono facili da esplorare. Non è visibile un'opzione per leggere la documentazione in un'altra lingua diversa dall'inglese. Non contiene alcuna descrizione delle caratteristiche.

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 Android ha poca o nessuna conoscenza tecnica. Ci sono però persone che hanno bisogno di informazioni più tecniche su una funzionalità. Scrivere e gestire due documenti separati per ciascuno degli scopi sopra indicati non è una buona idea. Oppure, persino nella stessa documentazione che divide una funzionalità in base a caratteristiche tecniche e non tecniche, crea ulteriore confusione. Poiché, ancora una volta, la maggior parte degli utenti è abituata all'interfaccia utente che vede o alle funzionalità che utilizza, non è facile per tutti decidere se si tratta di un argomento tecnico o non tecnico. Pertanto, vogliamo semplificare questa procedura.

-> La maggior parte degli utenti cercherà di ottenere informazioni attraverso lo smartphone stesso e si fermerà tramite il computer o altri dispositivi. Pertanto, la documentazione deve essere facilmente adattabile a tutte le dimensioni dello schermo. Non deve creare confusione in merito alla 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é l'applicazione desktop è in fase di sviluppo da molto tempo e ha raggiunto una sorta di saturazione, al contrario la porta per dispositivi mobili è relativamente nuova e ancora in fase di sviluppo. A parte questo, anche se oggi i dispositivi mobili stanno diventando così potenti, esiste un'evidente limitazione sul tipo di funzionalità che possiamo incorporare, soprattutto a causa della domanda dell'utente finale. Avere una funzionalità che nessuno usa significa sprecare risorse di sviluppo. Non è quindi consigliabile discutere entrambe la documentazione sulla base delle funzionalità.

IN BASE ALL'ANALISI PRECEDENTE, PROPONIRO QUANTO SEGUE. 1. Attualmente la documentazione per gli utenti di computer utilizza il generatore di documentazione Sphinx e il tema Leggi il tema Documenti. Usare lo stesso per la porta Android ci aiuterà nei seguenti modi: -> Facile unione di entrambe la documentazione. -> È ottimizzato per schermi di tutte le dimensioni. -> Esperienza fluida durante il passaggio alla Documentazione dell'utente di Android tramite la documentazione desktop

Separare capitoli, sezioni e 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à

Altre

|__Impostazioni

| |__Libreria multimediale

| |__Video -->Modalità background/PIP

: -> Questo approccio migliorerà la facilità di accesso perché gli utenti potranno passare facilmente al punto in cui hanno bisogno di aiuto confrontandolo con la posizione relativa all'interno dell'applicazione. Per ciascuna funzionalità possiamo separare ulteriormente la parte tecnica da quella non tecnica. Prima scriveremo una semplice descrizione non tecnica, quindi evidenzieremo o evidenzieremo ulteriormente le parti tecniche della stessa funzionalità, se presenti, appena sotto. Questo potrebbe comportare delle ripetizioni, ma garantirà un'esperienza senza problemi della maggioranza non tecnica. Ciò sarà utile anche in futuro per il miglioramento della manutenibilità. Poiché l'applicazione raggiungerà lo stato di saturazione, l'UI relativa non cambierà molto, quindi in futuro, se viene aggiunta/rimossa una nuova funzionalità, potremo semplicemente eseguire il refactoring della sezione. Nel caso in cui cambiasse l'intera UI, possiamo riorganizzare le sezioni/i capitoli o riorganizzare l'intero documento. In entrambi i casi, dobbiamo modificare l'intera documentazione perché lo screenshot dovrà essere sostituito in modo che corrisponda all'interfaccia utente corrente. Una demo funzionante è ospitata qui : https://avinal.gitlab.io/vlc-android-docs/
Ogni sezione della documentazione deve essere costituita da uno screenshot etichettato , una descrizione della funzione, una parte più tecnica se presente e suggerimenti utili per la funzione.

-> Sviluppare in modo indipendente questa documentazione dell'utente dal desktop ci aiuterà a unire la documentazione in pochi passaggi senza che ciò influisca sulla documentazione attuale o sia interessata durante lo sviluppo. Propongo di inserire l'intera documentazione nella sezione Android della documentazione desktop una volta sviluppata e di creare un permalink per la documentazione di VLC per Android.

-> Ulteriori miglioramenti possono includere la riprogettazione della pagina iniziale della documentazione per gli utenti di Google Desktop per consentire agli utenti di scegliere direttamente il sistema operativo preferito e il reindirizzamento alla documentazione del sistema operativo scelto. Poiché la documentazione per gli utenti di VLC per Windows, MacOS e Linux è già ben progettata e conversata, potremmo inserire delle opzioni tra cui scegliere Windows/MacOS/Linux o Android o iOS. In questo modo otterrai una documentazione utente ben separata ma unificata con un solo link da utilizzare per tutte le porte.

PERCHÉ LA MIA DOCUMENTAZIONE DELL'UTENTE PROPOSTA È MIGLIORE? La documentazione per gli utenti proposta è strutturata sulla base di pattern comuni seguiti dall'utente finale per richiedere assistenza. La documentazione combina tutte le funzionalità richieste, ad esempio semplicità, chiarezza, aspetto e conoscenze tecnologiche per massimizzare la facilità d'uso e l'esperienza dell'utente finale. Inoltre, questa opzione è facilmente gestibile, poiché non è più necessaria la gestione della documentazione dell'utente individuale per ogni porta.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO? -> Sto scrivendo codici da due anni e spesso ho bisogno di consultare la documentazione dell'API per alcune librerie o alcuni software o persino documentare il mio codice. Quindi so esattamente cosa vogliono vedere nella documentazione, quale problema devono affrontare e come si approcciano per ottenere aiuto. Sarò in grado di applicare la stessa esperienza per scrivere una documentazione coerente e facilmente leggibile.

-> Ho scritto attivamente materiale tecnico su Quora, Stack Overflow e varie altre piattaforme. So come spiegare le cose in modo accattivante e facilmente comprensibile.

-> VLC per Android è uno strumento potente e molto famoso, ma la maggior parte delle sue funzionalità sono sconosciute o non è disponibile alcun aiuto. Utilizzo VLC sia su piattaforme desktop che su piattaforme mobile da molti anni e so quali problemi potrebbe riscontrare un utente. Grazie a tutte le mie conoscenze ed esperienze, posso garantire un'ottima documentazione.