Progetto VideoLAN

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:

VideoLAN

Technical writer:

Edidiong Anny Asikpo

Nome progetto:

Modernizzare (riscrivere) la documentazione utente di VLC

Durata del progetto:

Durata standard (3 mesi)

Project description

SINTESI

La documentazione per gli utenti è progettata per aiutare gli utenti finali a utilizzare un prodotto o servizio. Una buona documentazione utente è molto importante perché fornisce agli utenti un mezzo per imparare a utilizzare un software, le sue funzioni, suggerimenti, trucchi e anche risolvere problemi comuni riscontrati durante l'utilizzo del software. Riduce inoltre i costi di assistenza ed è parte dell'identità aziendale del prodotto: una buona documentazione per gli utenti è un segnale di integrità del prodotto, il team di sviluppatori.

Senza una buona documentazione per l'utente, l'utente potrebbe non sapere come svolgere le operazioni sopra descritte in modo efficace ed efficiente. La documentazione per l'utente può svolgere un ruolo fondamentale nel garantire il successo di un prodotto, perché un'ottima comunicazione è e sarà sempre al centro di qualsiasi attività o prodotto, mentre un'ottima documentazione si limita a inserire tale comunicazione in una struttura gestibile a cui tutti possono accedere per il successo.

Al momento della stesura di questo articolo, la documentazione utente di VLC è stata consultata 4.634.065 volte e il media player VLC viene scaricato circa 23 milioni di volte al mese dal sito web principale, questo dimostra che molte persone in tutto il mondo utilizzano VLC Media Player e potrebbero voler leggere la sua documentazione utente per indicazioni su come utilizzare il media player. Tuttavia, la documentazione per l'utente del media player VLC è attualmente obsoleta e incompleta (è stata modificata l'ultima volta il 28 ottobre 2015) e la community di VideoLAN vuole utilizzare questo progetto per migliorare la propria documentazione utente al fine di consentire agli utenti finali di avere un'esperienza ottimale durante l'utilizzo del media player VLC.

STATO ATTUALE

Attualmente, la documentazione utente è disponibile su una pagina wiki. È obsoleto, incompleto, difficile da navigare o da trovare informazioni, non copre le informazioni sulla versione corrente del lettore multimediale e può essere tradotto soltanto in tedesco, il che comporta una grave difficoltà per le persone che non sanno leggere la lingua inglese.

PERCHÉ LA MIA DOCUMENTAZIONE DELL'UTENTE PROPOSTA È MIGLIORARE QUELLA ATTUALE?

La documentazione per gli utenti proposta sarà strutturata in modo da migliorare e garantire efficienza, coerenza e tranquillità per l'utente finale. L'articolo conterrà guide scritte e le relative immagini associate, istruzioni e spiegazioni su come utilizzare ciascuna funzionalità del media player VLC, aggiornate, di facile navigazione, comprensibili e traducibili in almeno cinque lingue principali.

Mentori: Jean-Baptiste, Alex, Simon

ANALISI

Jean-Baptiste e io abbiamo parlato del nuovo ambiente in cui sarebbe stata eseguita la migrazione dell'attuale documentazione utente per migliorarlo. Ha condiviso due link che mostravano un repository Gitlab del file sorgente scritto con Sphinx e la documentazione principale ospitata su Read the Docs. Ha dichiarato che si aspettavano che la nuova documentazione fosse simile a questa. Ho fatto molte ricerche su questi strumenti per capire meglio come funzionano.

Sfinge

Sphinx è una soluzione solida e matura per la documentazione del software. Include una serie di funzionalità che gli autori si aspettano, come la pubblicazione su un'unica fonte, il riutilizzo dei contenuti tramite include, l'inclusione condizionale in base al tipo di contenuti e ai tag, diversi temi HTML inappropriati per i minori che offrono un'ottima esperienza utente su dispositivi mobili e desktop, facendo riferimento a pagine, documenti e progetti. Supporto di indici e glossari e supporto di internazionalizzazione. Inoltre, utilizza reStructuredText come linguaggio di markup e molti dei suoi punti di forza derivano dalla potenza e dalla semplicità di reStructuredText e dalla sua capacità di tradurre la documentazione.

Leggi la documentazione

Leggi la documentazione semplifica la documentazione del software automatizzando la creazione, il controllo delle versioni e l'hosting dei tuoi documenti. Non scompare mai; in altre parole, ogni volta che esegui il push del codice sul tuo sistema di controllo della versione preferito, che sia Git, Mercurial, Bazaar o Subversion, Read the Docs crea automaticamente i tuoi documenti in modo che il tuo codice e la tua documentazione siano sempre aggiornati. Ha più versioni: Read the Docs può ospitare e creare più versioni dei tuoi documenti, quindi avere una versione 1.0 dei tuoi documenti e una versione 2.0 dei tuoi documenti è facile come avere un ramo o un tag separato nel tuo sistema di controllo della versione. Leggi i documenti è senza costi e open source e ospita documentazione per quasi 100.000 progetti open source di grandi e piccole dimensioni in quasi ogni linguaggio umano e informatico.

VERDETTO

Sphinx è uno strumento incredibilmente potente e Read the Docs si basa sulla parte superiore per fornire l'hosting della documentazione di Sphinx e mantenere aggiornati i documenti su più versioni. Insieme, rappresentano un fantastico insieme di strumenti che sviluppatori e tecnici possono utilizzare per creare la documentazione dell'utente più adatta agli utenti finali.

Sphinx include il supporto per la traduzione della documentazione in più lingue. Supporta il controllo della versione, che verrà utilizzato per gestire la documentazione. A differenza del wiki attuale, in cui chiunque può modificare e non aggiungere le informazioni corrette, questo sistema di controllo della versione garantisce che tutte le modifiche vengano esaminate prima di essere unite al repository principale. Il controllo della versione contribuirà inoltre all'aumento della documentazione open source per il progetto perché le persone possono creare problemi, aprire richieste di pull e così via. Sphinx e leggere i documenti è utilizzato da un elenco di altre grandi community come ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs e così via, ed è un ottimo strumento da usare per la nuova documentazione utente di VLC.

Non appena ho letto le informazioni su questi strumenti, ho anche creato un esempio di base. Questo è il link: https://gitlab.com/Didicodes/demo-vlc-user-documentation al mio repository Gitlab, mentre la versione ospitata su readthedocs è disponibile qui: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

STRUTTURA DELLA DOCUMENTAZIONE PROPOSTA

Ho creato una struttura per la documentazione dell'utente di VLC, che puoi trovare qui: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Prima che inizi l'implementazione, questa nuova struttura deve essere approvata dai mentori. Ciò significa che è probabile che la struttura cambi dopo essere stata esaminata dai mentori.

OBIETTIVI DEL PROGETTO

• Ristruttura la documentazione.
• Aggiorna la documentazione affinché si adatti alle versioni moderne di VLC.
• Esegui la migrazione della documentazione utente a Gitlab utilizzando Sphinx e ReadtheDocs.
• Rimuovi le immagini e le informazioni obsolete.
• Riscrivi la documentazione per l'utente per renderla più comprensibile.
• Configurala per la traduzione utilizzando l'internazionalizzazione Sphinx.
• Fai in modo che la community di documentazione sia guidata in modo che gli utenti possano segnalare o risolvere eventuali problemi riscontrati durante la lettura della documentazione.

PERCHÉ QUESTO PROGETTO?

Ho sempre avuto la convinzione che scrivere codice, risolvere problemi e creare software raggiunga il suo pieno potenziale quando si ha anche la capacità di illuminare gli altri attraverso la scrittura. Personalmente, sono sempre stato affascinato dagli sforzi compiuti dalla community di VideoLAN nella creazione di soluzioni software senza costi per il multimediale. Fin da bambino, il media player VLC è sempre stato il software che ho utilizzato per ascoltare musica o guardare un film, perché era molto rumoroso e composto da tante funzionalità. Sarà un onore lavorare con la community che ha contribuito a rendere la mia infanzia fantastica.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO

Credo di essere la persona giusta per questo progetto perché:

• Ho esperienza nel miglioramento della documentazione delle organizzazioni e posso utilizzare qualsiasi sistema di controllo della versione, quindi l'esecuzione di comandi su Gitab non sarà un problema. Inoltre, ciò che mi spinge è lavorare a progetti che creano valore per le persone.
• Credo che se vuoi che qualcuno faccia qualcosa nel modo più efficiente possibile, la documenti. Documentando i tuoi processi, garantisci efficienza, coerenza e tranquillità per tutte le persone coinvolte.
• Conosco le esigenze degli utenti di VLC perché sono uno di loro. In questo modo, potrai scrivere la documentazione in modo che tutti gli utenti in tutto il mondo possano comprenderla a colpo d'occhio.