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:
- VLC
- Redattore tecnico:
- Abhishek Pratap Singh
- Nome del progetto:
- Continuare la modernizzazione della documentazione utente di VLC
- Durata del progetto:
- Durata standard (3 mesi)
Project description
STATO ATTUALE DELLA DOCUMENTAZIONE
La documentazione utente di VLC è in fase di modernizzazione e aggiornamento. È in corso la transizione dalla documentazione precedente basata su wiki[1] alla moderna documentazione utente basata su Sphinx[2] ospitata su ReadTheDocs.
PUBBLICO DI DESTINAZIONE
Il pubblico di destinazione è sia un utente curioso che vuole esplorare le funzionalità di VLC Media Player oltre a un normale media player, sia, in una certa misura, gli sviluppatori, in quanto fungerà da guida di riferimento facile. Pertanto, ho intenzione di includere sia le istruzioni basate sulla GUI (insieme alle immagini, se pertinenti) sia i metodi basati sulla CLI (insieme agli snippet di codice) in modo che l'utente finale abbia la libertà di scelta.
Ritengo che il linguaggio della documentazione (in particolare la sezione relativa all'interfaccia utente) debba essere sufficientemente attenuato in modo che una persona con un'esposizione nominale all'utilizzo di computer possa comprendere e implementare la guida. D'altra parte, non deve essere troppo lungo o esplicativo (soprattutto nella sezione dell'interfaccia a riga di comando) in modo che i programmatori perdano interesse.
Il giusto equilibrio può essere raggiunto menzionando i prerequisiti all'inizio della pagina o mantenendo sezioni facoltative che gli esperti possono saltare.
Per la creazione delle traduzioni, il pubblico di destinazione è costituito dagli sviluppatori/utenti di VLC che hanno una buona conoscenza dell'inglese e della lingua in cui tradurranno.
STRUMENTI
La nuova documentazione viene creata da Sphinx e ospitata su ReadTheDocs, mentre il sistema di controllo della versione è implementato in GitLab. In passato ho utilizzato Git e GitHub, il che mi ha aiutato a capire GitLab, anche se alcune funzionalità diverse hanno richiesto un po' di tempo per essere apprese.
Per quanto riguarda Sphinx, l'ho letto quando un appassionato di open source ha sottolineato quante organizzazioni lo utilizzano per creare la propria documentazione (con l'esempio notevole di Blender, che utilizza Sphinx per creare il manuale dell'utente[3] e la documentazione dell'API[4]).
Conoscevo un po' ReadTheDocs, che è un buon strumento per il controllo delle versioni e per l'hosting della documentazione tecnica. Di conseguenza, ho potuto creare la documentazione di VLC senza molti problemi e ho dimestichezza con reStructured Text, la formattazione utilizzata.
Per le traduzioni, VLC utilizza Babel per generare file .po al fine di implementare i18n e l10n. Al momento sto studiando il flusso di lavoro di Babel e come creare file .mo utilizzando Sphinx.
Intendo utilizzare questo periodo per acquisire familiarità con le complessità degli strumenti di cui sopra.
ELEMENTI FORNITI E CALENDARIO SETTIMANALE
Nell'ambito del progetto del 2019, parti di installazione, interfaccia, audio, video, riproduzione e così via (la maggior parte delle funzionalità di base) sono già coperte. Pertanto, per il progetto del 2020, vorrei aggiornare e lavorare alla sezione relativa all'utilizzo avanzato della documentazione utente.
OUTPUT 1 [Settimana 1-2]: aggiorna la documentazione di transcodifica, come indicato nel punto 7[5].
- Transcodifica
- Transcodifica più video
- Aggiungi un logo
- Unire più video
- Estrai audio ed Estrai audio da un file
- Rippare un DVD
DELIVERABLE 2 [Week 3-4]: Aggiornamento sull'utilizzo di VLC come plug-in web[6], durante i test in Firefox 77, Chrome 83 ed Edge 83.
- Creare pagine web con video
- Attributi tag incorporati
- Descrizione dell'API JavaScript
CONSEGNABILE 3 [Settimana 5]: Testare i comandi dell’interfaccia a riga di comando[7] ed eseguire l’aggiornamento di conseguenza.
- Stream
- Selezione dei moduli
- Opzioni specifiche per articolo
- Filtri
Settimana 6: settimana di riserva per i tre elementi sopra indicati.
OUTPUT 4 [Settimane 7-8]: Preparazione delle traduzioni. Oltre all'aggiornamento, mi preparo per le traduzioni in altre lingue. Questo è importante perché, dopo la traduzione, gli utenti senza esperienza in inglese sarebbero in grado di leggere la documentazione (e, come nota a lato, VLC sarebbe un passo avanti per raggiungere il World Domination[8]).
Come indicato nella sezione Strumenti della proposta, al momento VLC utilizza Babel per generare file .po per le traduzioni. Documenterò la procedura per consentire a un utente/volontario di:
- Scarica e crea la documentazione di base localmente.
- Utilizza Babel per generare i file richiesti.
- Inserisci le traduzioni per le stringhe.
- Creazione della documentazione tradotta utilizzando Sphinx.
- Esegui il commit delle modifiche.
DOCUMENTO 5 [Settimana 9-10]: Preparazione della documentazione dei moduli. Come discusso con i mentor, ho intenzione di preparare la documentazione dei moduli in due parti.
Parte I: creazione di file vicino ai moduli tramite uno script che cerca opzioni valide nel codice di base ed estrae il loro utilizzo in una riga (e i valori predefiniti) dalle pagine wiki corrispondenti. Questa sarà una bozza di base.
Parte II: creazione di una struttura specifica per la piattaforma che collega 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 garantisce che la documentazione sia vicina al codice sorgente. Utilizzando un approccio dal basso verso l'alto, la documentazione principale dei moduli verrebbe creata combinando i file creati nella Parte I e utilizzando la struttura creata nella Parte II come riferimento.
I file creati tramite automazione richiedono una revisione, ma la prima priorità è creare un framework funzionale. Una volta completata questa operazione, in base al tempo a disposizione, esaminerò i file per verificare le opzioni. Stiamo dando priorità al framework poiché, una volta disponibile, gli sviluppatori e i gestori possono anche iniziare a dare il loro contributo aggiungendo casi d'uso pertinenti.
DOCUMENTO BONUS [Settimana 11]: preparati per la release 4.0. Se il progetto rimane in programma, vorrei proporti un deliverable extra. Come discusso con i mentor, la preparazione per il rilascio della versione 4.0 implica la disponibilità di una documentazione stabile e quasi completa per la versione 3.0.
Pertanto, esaminerò 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 e trucchi.
- Utilizzo avanzato: player, interfaccia, transcodifica, streaming, casi insoliti.
- Componenti aggiuntivi: estensioni, skin.
Settimana 12: settimana di buffer per i tre deliverable sopra indicati + report finali.
PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO?
Da appassionato di tecnologia, ho esperienza nell'uso/testare software e, in alcuni casi, cercare di dare un senso alla base di codice. In effetti, cercare di capire il codebase di un'organizzazione open source è stata la prima volta che mi sono veramente resa conto dell'importanza della documentazione. Inoltre, essendo un appassionato di musica, ho molta esperienza con le modifiche di VLC :)
A parte questo, sono stato ricercatore e scrittore per tutta la vita. A meno che non scriva qualcosa, non lo capisco mai veramente e questa abitudine mi ha reso un'efficiente trascrittore e documentarista.
L'intersezione di queste due abitudini è ciò che mi rende ideale per la documentazione tecnica. Posso orientarmi tra gli aspetti tecnici e documentare i miei risultati/processi in un modo comprensibile per gli utenti.
Link: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readdocs.io/en/latest/index.html [3] https://docs.blender.org/manual/it/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35