Progetto VideoLAN

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

Riepilogo del progetto

Organizzazione open source:

VideoLAN

Technical writer:

Edidiong Anny Asikpo

Nome progetto:

Modernizzare (riscrivere) la documentazione dell'utente VLC

Durata del progetto:

Durata standard (3 mesi)

Project description

RIEPILOGO

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

Senza una buona documentazione, l'utente potrebbe non sapere come svolgere le attività sopra descritte in modo efficace ed efficiente. La documentazione dell'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 e un'ottima documentazione prende questa comunicazione e la inserisce in una struttura gestibile a cui tutti possono accedere per il successo.

Al momento della stesura di questo documento, la documentazione utente 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, ciò 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 dell'utente e consentire agli utenti finali di avere un'esperienza ottimale durante l'utilizzo del media player VLC.

STATO ATTUALE

Attualmente, la documentazione dell'utente è disponibile su una pagina wiki. È obsoleto, incompleto, difficile da consultare o trovare informazioni, non copre le informazioni sulla versione corrente del media player e può essere tradotto solo in tedesco, il che causa un grave disagio per le persone che non sanno leggere la lingua inglese.

PERCHÉ LA MIA DOCUMENTAZIONE DELL'UTENTE PROPOSTA È UN MIGLIORAMENTO SU QUELLA ATTUALE?

La documentazione per l'utente proposta sarà strutturata in modo da migliorare e garantire efficienza, coerenza e tranquillità per l'utente finale. Conterrà guide scritte e le relative immagini associate, istruzioni e spiegazioni su come utilizzare ciascuna funzionalità del media player VLC, aggiornate, facili da esplorare, 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 dell'utente per migliorarla. 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 detto 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 software. Include una serie di funzionalità che gli autori si aspettano, come la pubblicazione di un'unica fonte, il riutilizzo dei contenuti tramite include, le funzionalità condizionali basate sul tipo di contenuti e i 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 Indice e Glossario e supporto all'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: ogni volta che esegui il push del codice nel tuo sistema di controllo della versione preferito, Git, Mercurial, Bazaar o Subversion, Read the Docs crea automaticamente i tuoi documenti in modo che il codice e la documentazione siano sempre aggiornati. Ha più versioni; Leggi i documenti può ospitare e creare più versioni dei tuoi documenti in modo che avere una versione 1.0 e una versione 2.0 dei tuoi documenti è facile come avere un ramo o 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 tutti i linguaggi umani e informatici.

VERDETTO

Sphinx è uno strumento incredibilmente potente e la funzionalità Leggi i documenti si basa su un supporto per fornire l'hosting della documentazione Sphinx e mantenere i documenti aggiornati in tutte le versioni. Insieme, rappresentano un meraviglioso insieme di strumenti che sviluppatori e tecnici possono utilizzare per creare documentazione per l'utente ottimale per gli 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 dell'attuale wiki 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 aumenterà anche il contributo della documentazione open source al 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, ecc. ed è un ottimo strumento da utilizzare per la nuova documentazione utente VLC.

Non ho appena letto di questi strumenti, ma 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 utente di VLC, disponibile qui: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Prima che l'implementazione di questa nuova struttura inizi, deve essere approvata dai mentori. Questo significa che è probabile che la struttura cambi dopo essere stata esaminata dai mentori.

OBIETTIVI DEL PROGETTO

• Ristruttura la documentazione.
• Aggiorna la documentazione per adattarla 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.
• Configuralo per la traduzione utilizzando l'internazionalizzazione Sphinx.
• Fai in modo che la community della documentazione sia gestita dalla community, in modo che gli utenti possano segnalare o risolvere eventuali problemi riscontrati durante la lettura della documentazione.

PERCHÉ QUESTO PROGETTO?

Sono sempre stata convinta che scrivere codice, risolvere problemi e creare software raggiungano il suo pieno potenziale quando si ha anche la capacità di illuminare altre persone in merito attraverso la scrittura. Personalmente, sono sempre stato affascinato dagli sforzi compiuti dalla community di VideoLAN nella creazione di soluzioni software senza costi per i contenuti multimediali. Crescendo, il media player VLC è sempre stato il software che utilizzavo per ascoltare musica o guardare un film, perché era molto rumoroso e comprendeva tantissime funzionalità. Sarà un onore lavorare con la community che ha contribuito a rendere la mia infanzia meravigliosa.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO

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

• Ho esperienza nel migliorare la 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 è a 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 processi, garantisci efficienza, coerenza e tranquillità a tutte le persone coinvolte.
• Conosco le esigenze degli utenti di VLC perché sono uno di loro. In questo modo, scriverai la documentazione in modo tale che tutti gli utenti in tutto il mondo possano comprenderli a colpo d'occhio.