Progetto VLC

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

Riepilogo del progetto

Organizzazione open source:

VLC

Technical writer:

Abhishek Pratap Singh

Nome progetto:

Continua la documentazione per gli utenti di VLC sulla modernizzazione

Durata del progetto:

Durata standard (3 mesi)

Project description

STATO ATTUALE DELLA DOCUMENTAZIONE

La documentazione utente di VLC è in fase di modernizzazione e aggiornamento. La transizione è in corso per passare dalla precedente documentazione basata su wiki[1] alla documentazione utente moderna creata da Sphinx[2] ospitata su ReadTheDocs.

PUBBLICO DI DESTINAZIONE

Il pubblico di destinazione è un utente curioso che desidera esplorare le funzionalità del media player VLC al di là di un normale media player e, in una certa misura, aiuterà anche gli sviluppatori fungendo da semplice guida di riferimento. Pertanto, ho intenzione di includere sia istruzioni basate su GUI (insieme alle immagini, se pertinenti) sia metodi basati su interfaccia a riga di comando (insieme agli snippet di codice) in modo che l'utente finale abbia la libertà di scelta.

Credo che il linguaggio della documentazione (in particolare la sezione GUI) debba essere ridotto in modo tale che una persona con un'esposizione nominale all'utilizzo dei computer sia in grado di comprendere e implementare la guida. D'altra parte, non dovrebbe essere troppo lungo o esplicativo (in particolare nella sezione dell'interfaccia a riga di comando) che i programmatori perdano interesse.

Il giusto equilibrio può essere raggiunto menzionando i prerequisiti all'inizio della pagina o mantenendo sezioni facoltative che i più esperti possono saltare.

Per la creazione delle traduzioni, il pubblico di destinazione è costituito dagli sviluppatori/utenti di VLC con una buona conoscenza dell'inglese e della lingua in cui tradurre.

STRUMENTI

La nuova documentazione è stata creata da Sphinx ed è ospitata su ReadTheDocs, mentre il sistema di controllo della versione è implementato in GitLab. Ho avuto un'esperienza passata con Git e GitHub e questo mi ha aiutato a imparare a conoscere GitLab, anche se c'erano alcune funzionalità diverse che richiedevano un po' di tempo per imparare.

Per quanto riguarda Sphinx, ne avevo letto quando un collega appassionato di open source aveva notato quante organizzazioni lo stanno usando per creare la propria documentazione (con il notevole esempio di Blender, che utilizza Sphinx per creare il loro manuale dell'utente[3] e la documentazione API[4]).

Conoscevo un po' ReadTheDocs, che è un ottimo strumento per il controllo delle versioni e per l'hosting di documentazione tecnica. Di conseguenza, sono riuscito a creare la documentazione VLC senza molti problemi e ho familiarità con il testo ristrutturato, la formattazione utilizzata.

Per le traduzioni, VLC utilizza Babel per generare file .po al fine di implementare i18n e l10n. Attualmente sto dimestichezza con il flusso di lavoro di Babel e come creare file .mo usando Sphinx.

Intendo utilizzare il periodo di collegamento per familiarizzare ulteriormente con le complessità degli strumenti di cui sopra.

DA CONSEGNARE E CRONOLOGIA SETTIMANALE

Nell'ambito del progetto del 2019, sono già incluse le sezioni relative a installazione, interfaccia, audio, video, riproduzione e così via (la maggior parte delle funzionalità di base). Pertanto, per il progetto del 2020, vorrei aggiornare e lavorare sulla sezione Utilizzo avanzato della documentazione per gli utenti.

CONSEGNA 1 [Settimana1-2]: Aggiornamento della documentazione di transcodifica, come menzionato al #7[5].

• Transcodifica
• Transcodifica più video
• Aggiungi un logo
• Unisci video
• Estrarre l'audio ed estrarre l'audio da un file
• Copia un DVD

CONSEGNA 2 [Settimana 3-4]: Aggiornamento utilizzando VLC come plug-in web[6], durante il test in Firefox 77, Chrome 83 ed Edge 83.

• Creazione di pagine web con video
• Attributi tag incorporati
• Descrizione API JavaScript

CONSEGNA 3 [Settimana 5]: Testa i comandi dell'interfaccia a riga di comando[7] e aggiornali di conseguenza.

• Stream
• Selezione dei moduli
• Opzioni specifiche dell'elemento
• Filtri

Settimana 6: settimana del buffer per le tre consegne precedenti.

DA CONSEGNARE 4 [Settimana 7-8]: Preparati per le traduzioni. Oltre ad aggiornare i dati, mi preparo per le traduzioni in altre lingue. Questo è importante perché dopo la traduzione, gli utenti che non hanno background in inglese sarebbero in grado di leggere la documentazione (e, in una nota a margine, VLC sarebbe un passo più vicino per raggiungere la dominazione mondiale [8]).

Come menzionato nella sezione Strumenti della proposta, VLC attualmente utilizza Babel per generare file .po per le traduzioni. Documenterò la procedura per un utente/volontario per:

• Scarica e crea la documentazione di base in locale.
• Utilizza Babel per generare i file richiesti.
• Inserisci le traduzioni delle stringhe.
• Creazione della documentazione tradotta utilizzando Sphinx.
• Esegui il commit delle modifiche.

CONSEGNA 5 [Settimana 9-10]: preparati per la documentazione dei moduli. Come discusso con i mentori, prevedo di preparare la documentazione dei moduli in due parti.

Parte I: creare file vicino ai moduli tramite uno script che cerca opzioni valide dal codebase ed estrae il loro utilizzo di una riga (e i valori predefiniti) dalle pagine wiki corrispondenti. In questo modo si tratterebbe di una bozza di base.

Parte II: Creazione di una struttura specifica per la piattaforma che colleghi tutti i moduli, i plug-in e le opzioni per una determinata piattaforma (Windows e, se il tempo lo consente, anche per Fedora).

La creazione di file vicino ai moduli garantirà che la documentazione sia vicina al codice sorgente. Utilizzando un approccio dal basso verso l'alto, la documentazione dei Moduli principali verrebbe creata combinando i file creati nella Parte I e utilizzando come riferimento la struttura realizzata nella Parte II.

I file creati tramite l'automazione richiedono una revisione, ma la prima priorità è creare un framework funzionale. Una volta ottenuto questo risultato e in base al tempo a disposizione, esaminerò i file per verificare le opzioni. Il framework ha la priorità poiché, una volta disponibile, gli sviluppatori e i gestori possono anche iniziare a contribuire aggiungendo casi d'uso pertinenti.

BONUS CONSEGNABILE [Settimana 11]: preparati per la release 4.0. Se il progetto rimane in linea con i tempi, vorrei proporre un prodotto da consegnare extra. Come discusso con i mentori, prepararsi alla versione 4.0 implica avere una documentazione stabile e quasi completa per la versione 3.0.

Pertanto, ti conviene consultare la documentazione già completata delle seguenti sezioni per verificare e aggiornare i metodi indicati:

• Utilizzo di base: contenuti multimediali, riproduzione, audio, video, sottotitoli, tasti di scelta rapida, registrazioni, impostazioni, suggerimenti utili.
• Utilizzo avanzato: player, interfaccia, transcodifica, streaming, casi insoliti.
• Componenti aggiuntivi: estensioni, skin.

Settimana 12: Settimana del buffer per i tre risultati precedenti + Report finali.

PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO?

Sono un appassionato di tecnologia, ho esperienza nell'uso/test dei software e, a volte, ho provato a dare un senso alle loro codebase. In effetti, cercare di comprendere il codebase di un'organizzazione open source è stata la prima volta in cui ho capito davvero l'importanza della documentazione. Inoltre, come appassionato di musica, ho molta esperienza nelle modifiche con VLC :)

A parte questo, sono stata ricercatrice e scrittrice per tutta la vita. Se non scrivo qualcosa, non riesco a capire davvero e questa abitudine mi ha reso un'efficiente organizzazione di appunti e documentari.

L'intersezione di queste due abitudini è ciò che mi rende adatto alla documentazione tecnica. Riesco a orientarmi tra gli aspetti tecnici e a documentare i miei risultati/processi in modo che gli utenti possano comprenderli.

Link: [1] https://wiki.videolan.org/Documentazione:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.lcvlan/editor/