Progetto VideoLAN

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:

VideoLAN

Technical Writer:

Edidiong Anny Asikpo

Nome del progetto:

Eseguire la modernizzazione (riscrittura) della documentazione utente di VLC

Durata del progetto:

Durata standard (3 mesi)

Project description

ABSTRACT

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

Senza una buona documentazione utente, un utente potrebbe non sapere come eseguire le operazioni precedenti in modo efficace ed efficiente. La documentazione utente può svolgere un ruolo fondamentale per garantire il successo di un prodotto perché una comunicazione efficace è e sarà sempre al centro di qualsiasi attività o prodotto e una buona documentazione prende questa comunicazione e la inserisce in un framework gestibile a cui tutti possono accedere per ottenere risultati.

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 ogni mese dal sito web principale. Ciò dimostra che molte persone in tutto il mondo utilizzano VLC Media Player e potrebbero voler leggere la relativa documentazione utente per avere indicazioni su come utilizzarlo. Tuttavia, la documentazione utente di VLC Media Player è attualmente obsoleta e incompleta (l'ultima modifica è stata apportata il 28 ottobre 2015) e la community di VideoLAN vuole utilizzare questo progetto per migliorare la documentazione utente in modo da consentire agli utenti finali di avere un'esperienza fluida quando utilizzano VLC Media Player.

STATO ATTUALE

Attualmente la documentazione per gli utenti è disponibile su una pagina wiki. Sono obsolete, incomplete, difficili da consultare o da trovare, non coprono le informazioni sulla versione corrente del media player e possono essere tradotti solo in tedesco, il che causa un grave disagio per chi non sa leggere la lingua inglese.

PERCHÉ LA DOCUMENTAZIONE PER GLI UTENTI CHE PROPONGO È UN MIGLIORAMENTO RISPETTO A QUELLA ATTUALE?

La documentazione utente proposta sarà strutturata per migliorare e garantire efficienza, coerenza e tranquillità per un utente finale. Dovranno contenere guide scritte e le relative immagini associate, includere istruzioni e spiegazioni su come utilizzare ogni funzionalità del media player VLC, essere aggiornate, facili da navigare, comprensibili e traducibili in almeno cinque lingue principali.

Mentori: Jean-Baptiste, Alex, Simon

ANALISI

Jean-Baptiste e io abbiamo parlato del nuovo ambiente a cui verrà eseguita la migrazione della documentazione utente attuale per i miglioramenti e 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 aspetta che la nuova documentazione sia simile. 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 da un'unica origine, il riutilizzo dei contenuti tramite include, gli include condizionali in base al tipo di contenuti e ai tag, più temi HTML maturi che offrono un'esperienza utente eccezionale su dispositivi mobili e computer, i riferimenti tra pagine, documenti e progetti supporto di indici e glossari e supporto per l'internazionalizzazione. Utilizza inoltre 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

Read the Docs semplifica la documentazione del software automatizzando la compilazione, il controllo delle versioni e l'hosting dei tuoi documenti. Non viene mai sincronizzato: ogni volta che esegui il push del codice al tuo sistema di controllo della versione preferito, che si tratti di Git, Mercurial, Bazaar o Subversion, Read the Documenti creerà automaticamente i tuoi documenti in modo che il codice e la 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 e una versione 2.0 dei tuoi documenti è facile come avere un ramo o un tag separato nel tuo sistema di controllo delle versioni. Leggi Documenti è senza costi e open source e contiene la documentazione per quasi 100.000 progetti open source grandi e piccoli in quasi tutti i linguaggi umani e informatici.

VERDETTO

Sphinx è uno strumento incredibilmente potente e Read the Docs si basa su questo per fornire l'hosting della documentazione di Sphinx che mantiene aggiornati i tuoi documenti tra le varie versioni. Insieme, rappresentano un meraviglioso insieme di strumenti che gli sviluppatori e i redattori tecnici possono utilizzare per creare la documentazione 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 della wiki attuale, in cui chiunque può modificare e non aggiungere le informazioni corrette, questo sistema di controllo delle versioni garantisce che tutte le modifiche vengano esaminate prima di essere unite al repository principale. Il controllo della versione aumenterà anche il contributo open source della documentazione al progetto perché le persone possono creare problemi, aprire richieste di pull e così via. Sphinx e leggere i documenti sono utilizzati da un elenco di altri grandi e community come ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, write the Docs e così via, ed è un ottimo strumento da utilizzare per la nuova documentazione utente di VLC.

Non ho solo 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, che puoi trovare qui: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Prima dell'inizio dell'implementazione di questa nuova struttura, deve essere approvata dai mentor. Ciò significa che è probabile che la struttura cambi dopo essere stata esaminata dai mentori.

OBIETTIVI DEL PROGETTO

• Ristrutturare la documentazione.
• Aggiorna la documentazione in base alle versioni moderne di VLC.
• Esegui la migrazione della documentazione utente a Gitlab utilizzando Sphinx e ReadtheDocs.
• Rimuovi le immagini e le informazioni obsolete.
• Riscrivere la documentazione utente per renderla più comprensibile.
• Configuralo per la traduzione utilizzando l'internazionalizzazione di Sphinx.
• Rendi la documentazione basata sulla community in modo che gli utenti possano segnalare o risolvere eventuali problemi riscontrati durante la lettura.

PERCHÉ QUESTO PROGETTO?

Ho sempre avuto la convinzione che scrivere codice, risolvere problemi e creare software raggiunga il suo pieno potenziale quando hai anche la capacità di illuminare gli altri al riguardo attraverso la scrittura. Personalmente, sono sempre stato affascinato dagli sforzi intrapresi dalla community di VideoLAN per creare soluzioni software senza costi per i contenuti multimediali. Da bambina, il media player VLC è sempre stato il software che usavo per ascoltare musica o guardare un film perché era molto potente e includeva tantissime funzionalità. Sarà un onore lavorare con la community che ha contribuito a rendere fantastica la mia infanzia.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO

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

• Ho esperienza passata nel migliorare la documentazione delle organizzazioni e posso utilizzare qualsiasi sistema di controllo della versione, quindi eseguire comandi su Gitab non sarà un problema. Inoltre, mi motiva lavorare a progetti che creano valore per le persone.
• Credo che se vuoi che qualcuno faccia qualcosa nel modo più efficiente possibile, devi documentarlo. Documentando le tue procedure, garantisci efficienza, coerenza e tranquillità a tutti i soggetti coinvolti.
• Conosco le esigenze degli utenti di VLC perché sono uno di loro. In questo modo potrai scrivere la documentazione in modo che ogni altro utente in tutto il mondo la capisca a prima vista.