Progetto Wikimedia Foundation

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:
Wikimedia Foundation
Redattore tecnico:
Pavithra Eswaramoorthy
Nome del progetto:
Miglioramento della documentazione per i documentaristi e i videografi tecnici di Wikimedia
Durata del progetto:
Durata standard (3 mesi)

Project description

1. Informazioni su di me

Il software open source mi è stato presentato qualche mese fa e mi sono quasi subito sopraffatto dalla portata illimitata. Mentre cercavo di orientarmi tra i miliardi di progetti, ho scoperto iniziative open source come Google Summer of Code e Outreachy. La stagione dei documenti di Google mi sembrava interessante e le idee di progetto della Wikimedia Foundation hanno stuzzicato la mia curiosità, quindi ho iniziato a esplorare ulteriormente.

Finora il mio percorso è stato allo stesso tempo entusiasmante e confuso, con frasi come "Aspetta, cosa?", "Ah, ho capito!" e "Dovrei commentare?". La community di Wikimedia mi ha supportato in ogni fase. Dalla modifica delle pagine alla creazione di estensioni, ho imparato qualcosa di nuovo ogni giorno.

Come previsto, la procedura di richiesta è stata il mio gateway per la community open source. Questa proposta è ispirata alle mie esperienze come principiante.

2. Progetto

2.1. Contorno

Questo progetto mira a migliorare la documentazione per i redattori tecnici e i potenziali videografi di Wikimedia. Un insieme maturo di linee guida per la documentazione tecnica contribuirebbe a migliorare la documentazione complessiva e i riferimenti per la creazione di screencast consentirebbero di dimostrare efficacemente le funzionalità del software. La documentazione esistente in queste aree può essere estesa per supportare meglio sia i nuovi arrivati sia i collaboratori esperti. Per sviluppare questa rete di risorse utili verrà adottato un approccio incrementale.

2.2. Materiali da produrre

  • T197006 [https://phabricator.wikimedia.org/T197006] - Migliorare la documentazione per i documentaristi di Wikimedia:

    • Aggiungi suggerimenti ed esempi alla documentazione/Guida di stile. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Aggiungi informazioni specifiche di MediaWiki a determinati generi nei modelli e nei suggerimenti per la documentazione tecnica: guide dell'utente, procedure dettagliate, guide rapide, note di rilascio e file README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Prova e migliora le linee guida per l'assegnazione della priorità alla documentazione tecnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Progetta una strategia di raccolta di contenuti per diversi generi di documentazione.
    • Progetta una strategia di comunicazione e collaborazione per la documentazione di MediaWiki.
    • Crea un elenco di controllo in base al quale gli autori possono rivedere i documenti prima della pubblicazione.
    • Espandere la struttura della documentazione per i nuovi autori tecnici. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Prepara un elenco delle attività di documentazione tecnica adatte agli hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Crea un hub per Technical Writer che rimandi a risorse utili.

  • Migliorare la documentazione per i videografi di MediaWiki:

    • Crea una guida rapida per gli utenti per realizzare uno screencast generale.
    • Progettare modelli di screencast specifici per MediaWiki per procedure dettagliate e tutorial.

  • T214522 [https://phabricator.wikimedia.org/T214522]- Creare uno screencast "Introduzione a Phabricator".

2.3. Obiettivo di stretching

  • Ricontrolla i contenuti e aggiorna la documentazione relativa a WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentori

Zulip sarà il canale di comunicazione principale con i miei mentor. Per le discussioni con la community verranno utilizzati i canali IRC e l'email di Wikimedia. Le discussioni su attività specifiche si svolgeranno nella sezione dei commenti delle attività di Phabricator.

4. Discussione

Questo progetto è suddiviso in due fasi:

(i) Migliorare le risorse esistenti per gli autori tecnici di Wikimedia.

(ii) Creare modelli utili per i potenziali videografi.

(i) Migliorare le risorse esistenti per i redattori tecnici di Wikimedia.

In passato sono state intraprese diverse iniziative per migliorare la documentazione di MediaWiki con risultati diversi. Ecco alcuni esempi:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Grazie a questi sforzi, possiamo capire che un insieme migliore di risorse per i Technical Writer avrà un impatto diretto sui documenti da loro generati.

Di seguito è riportato uno snippet del report bisettimanale di un'intern di Outreachy 2018, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

"La guida di stile di MediaWiki è tutt'altro che perfetta, soprattutto perché si basa troppo su riferimenti esterni senza mettere in evidenza le pratiche che considera le migliori. Purtroppo, questo problema non si limita solo a MediaWiki, in quanto si verifica anche in altre documentazioni, come le best practice per la traduzione. Gli autori finiscono per non avere risorse buone e affidabili per svolgere il proprio lavoro, il che comporta difficoltà a stabilire un pubblico di destinazione e uno stile di scrittura adeguato. Inoltre, gli utenti, in particolare i nuovi, potrebbero riscontrare problemi a comprendere nuovi concetti e procedure".

Il bug T197006 [https://phabricator.wikimedia.org/T197006] mette in luce anche alcune aree della documentazione di scrittura tecnica che richiedono miglioramenti. È chiaro che Documentation/Style_guide è il punto di partenza.

Una volta che avremo una guida di stile migliore, verrà pianificata la serie di documenti successiva per guidare gli autori tecnici attraverso le diverse fasi della scrittura tecnica. La documentazione deve essere adatta ai principianti e allo stesso tempo fornire tutte le informazioni necessarie a cui fare riferimento per gli autori.

La fase di preparazione è probabilmente la più importante, in quanto getta le basi su cui si basa il documento. Per supportare gli autori tecnici in questa fase, vengono sviluppati dei documenti di riferimento che descrivono alcuni modi efficaci di raccogliere informazioni pertinenti e suggerimenti su come strutturare queste informazioni utilizzando modelli.

Poi arriva la fase di scrittura. Ai copywriter vengono forniti esempi di buon lavoro per impostare automaticamente un livello elevato. Inoltre, viene creata una lista di controllo con una serie di criteri di base che ogni documento deve rispettare, per aiutare gli autori a rivedere i documenti prima della pubblicazione.

Anche con questi documenti, i nuovi Technical Writer avranno bisogno di ulteriore assistenza e noi dobbiamo darglielo. La guida per i nuovi autori di manuali tecnici è stata perfezionata e un elenco di attività adatte agli hackathon è stato selezionato in base al livello di difficoltà.

Infine, è stato testato e migliorato un documento per comprendere la procedura di gestione e manutenzione della documentazione: "Priorità della documentazione tecnica".

Al termine di questa fase, verrà creato un hub di guide, risorse, esempi, suggerimenti e modelli di scrittura tecnica a supporto della guida allo stile della documentazione.

(ii) Creare modelli utili per potenziali videografi.

"Uno dei modi più difficili per imparare tutto ciò che coinvolge la grafica è leggere il testo normale. Immagina anche cosa succede se il manuale fa riferimento alla versione sbagliata del software: con i manuali solo di testo spesso diventa impossibile ricreare una serie di azioni quando i menu e il testo dell'applicazione cambiano, perché mancano tutti gli indicatori che normalmente utilizziamo.

Forse il modo migliore per imparare è quando hai un esperto seduto accanto a te. Gli screencast sono tra una grafica statica e la presenza di un esperto. Abbiamo una demo visiva e in movimento con una voce amichevole, possiamo anche avere annotazioni di testo sullo schermo e animazioni. Un vantaggio degli screencast rispetto a un esperto è che possono essere riprodotti a piacere ogni ora di ogni giorno.

Possiamo anche aggiungere sottotitoli tradotti a uno screencast in modo che possano essere visualizzati da chi non parla la lingua madrelingua o sostituire la traccia audio con lingue alternative".

Nello snippet sopra tratto da "The Screencasting Handbook" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald spiega il significato degli screencast. Potrebbe essere particolarmente utile per i tutorial sulla configurazione dell'ambiente di sviluppo MediaWiki, sulla scrittura di estensioni, sull'utilizzo di Gerrit e altro ancora.

Come per i modelli di documenti, avere un modello standard per gli screencast favorisce l'uniformità e migliora l'esperienza dello spettatore. Inoltre, fornisce ai potenziali videografi un framework per iniziare. Di conseguenza, viene sviluppata una guida rapida per l'utente seguita da modelli per la creazione di video introduttivi e tutorial. La documentazione include indicazioni sulla profondità dei concetti da trattare e alcune idee per gli screencast di MediaWiki.

Il modo migliore per testare il modello riportato sopra e prepararsi per l'obiettivo di espansione è creare uno screencast utilizzando gli strumenti e i modelli. Viene quindi creato uno screencast "Introduzione a Phabricator" che illustra le nozioni di base sull'utilizzo di Phabricator. Questa procedura evidenzierà anche le aree che richiedono una discussione.

Infine, la fonte principale di riferimento per i videografi di Wikimedia, ovvero WikiProject Screencast, viene esaminata e aggiornata.

5. Tempistiche indicative

Periodo di creazione di legami con la community (1° agosto - 1° settembre)

  • Analizza il progetto in dettaglio con i miei mentor.

  • Discuti di:

    • La frequenza con cui devono essere esaminate le attività.
    • Condividi le programmazioni e decidi un flusso di lavoro settimanale/giornaliero.
    • Strumenti e risorse che possono essere utilizzati.
    • Report sui progetti bisettimanali e giornalieri.

  • Crea le attività e le attività secondarie richieste su Phabricator.

  • Crea bozze per compensare gli impegni personali durante la fase di sviluppo del documento.

Settimana 1 (2-8 settembre)

  • Migliora la documentazione/Style_guide:

    • Sposta l'attenzione principale sull'illustrazione delle best practice e degli standard su MediaWiki.
    • Includi esempi di buon lavoro e migliora la visibilità delle pagine associate.

  • Migliorare la guida per i nuovi scrittori tecnici:

    • Espandi la struttura della documentazione.

Settimana 2 (9-15 settembre)

  • Lavora all'assegnazione della priorità alla documentazione tecnica:

    • Valuta la bacheca di lavoro della documentazione; trova esempi di descrizioni e priorità delle attività efficaci.
    • Studia le tendenze e prendi nota delle difficoltà più comuni.
    • Utilizza le informazioni e gli esempi per documentare gli standard di priorità.

Settimana 3 (16-22 settembre)

  • Crea la seguente documentazione aggiuntiva per gli autori tecnici:

    • Un elenco di controllo per aiutarti a esaminare la documentazione tecnica prima della pubblicazione.
    • Metodi per raccogliere in modo efficace i contenuti per diversi generi di documentazione.

Settimana 4 (23-29 settembre)

  • Aggiungi informazioni sulla scrittura nei generi più comuni di MediaWiki a suggerimenti e modelli di documentazione tecnica:

    • Documenta le best practice su MediaWiki per la scrittura di guide per l'utente, guide rapide, file README, note di rilascio e procedure dettagliate.

  • Aggiungi indicazioni per migliorare la maturità della comunicazione tecnica. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Settimana 5 (30 settembre - 6 ottobre)

  • Migliora la documentazione per l'inserimento di nuovi collaboratori:

    • Aggiorna la pagina: Attività di documentazione tecnica per gli hackathon. (da fare: aggiungi attività appropriate a questa pagina per tutto il periodo del progetto)

  • Creare un hub per i redattori tecnici

    • Crea una pagina di destinazione con link a pagine e risorse utili.
    • Aggiungi i link necessari alle pagine nuove ed esistenti per spostarti più facilmente tra di esse.

Settimana 6 (7-13 ottobre)

  • Crea i seguenti documenti sulla creazione di video per MediaWiki:

    • Una breve guida per gli utenti sulla "creazione di uno screencast generale" che rimanda al progetto Screencast.
    • Modelli per: procedure dettagliate per l'utilizzo di un software/strumento; tutorial per lo sviluppo di nuovi strumenti.

  • Crea un elenco di idee per gli screencast di MediaWiki.

Settimana 7 (14-20 ottobre)

  • Lavora al video ""Introduzione a Phabricator"":

    • Utilizza il modello (creato la settimana precedente) per redigere la bozza di uno script.
    • Stimare l'efficienza del modello e migliorarlo se necessario.
    • Ricevi feedback e finalizza la bozza.

Settimana 8 (21-27 ottobre)

  • Pubblica il video "Introduzione a Phabricator":

    • Seleziona e installa il software.
    • Configura l'ambiente e crea lo screencast.
    • Prendi nota dei problemi riscontrati e delle soluzioni.

Settimana 9 (28 ottobre - 3 novembre)

  • Contribuisci a migliorare la documentazione del progetto Screencast:

    • Esamina la struttura e valuta la necessità di apportare modifiche.
    • Esamina i software menzionati.
    • Ricerca e aggiornamento dell'elenco dei software.

Settimana 10 (4-10 novembre)

  • Continuare a migliorare la documentazione del progetto Registra schermo:

    • Valuta e migliora il tutorial e gli script.
    • Esamina la galleria di screencast.

Settimana 11 (11-17 novembre)

  • Completa il lavoro sulla documentazione del progetto di Registra schermo:

    • Trova e aggiungi alla galleria i video più recenti.
    • Apporta le modifiche strutturali necessarie.

Settimana 12 (18-24 novembre)

  • Lavora su eventuali attività in sospeso.

  • Scrivi il report finale:

    • Fai riferimento ai report bisettimanali/giornalieri e raccogli le informazioni richieste.
    • Pianifica la struttura del report e scrivi una bozza.
    • Migliora e completa la bozza in base al feedback del mentor.

Settimana 13 (25-29 novembre)

  • Invia il report finale e la valutazione del mentor.

6. Monitoraggio dei progressi

Gli aggiornamenti giornalieri sui progressi verranno comunicati ai miei mentor tramite Zulip. La community di Wikimedia può tenere traccia dei miei progressi attraverso Phabricator o nei rapporti di progetto bisettimanali.

7. Altri impegni

Sono uno studente universitario a tempo pieno e il mio semestre accademico autunnale si sovrappone alla tempistica della Stagione di Documenti. Pertanto, i miei impegni includono gli esami universitari.

Primo esame interno: dal 18 al 24 agosto

Secondo esame interno: dal 29 settembre al 6 ottobre

Esame di fine semestre: dall'11 al 30 novembre

Inoltre, grazie alla posizione favorevole di quest'anno, ho intenzione di partecipare alla mia prima conferenza pubblica, PyCon India, dal 12 al 15 ottobre. Credo che sarebbe un'ottima opportunità per incontrare nuove persone e fare conversazioni approfondite.

Per gestire questi impegni, la sequenza temporale provvisoria contiene attività meno impegnative nelle settimane corrispondenti. Ho intenzione di completare non più di 20 crediti obbligatori nel semestre autunnale per avere tempo sufficiente per lo sviluppo della documentazione. (uno studente regolare completa in media 25 crediti a semestre)