Progetto Wikimedia Foundation

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

Riepilogo del progetto

Organizzazione open source:
Wikimedia Foundation
Technical writer:
Pavithra Eswaramoorthy
Nome progetto:
Miglioramento della documentazione per documentaristi e videografi tecnici di Wikimedia
Durata del progetto:
Durata standard (3 mesi)

Project description

1. Informazioni su di me

Qualche mese fa mi è stato introdotto il software open source e quasi subito mi sono sentito sopraffatto dal suo ambito illimitato. Mentre faticava a sbaragliare i grandi progetti, ho scoperto iniziative open source come Google Summer of Code e Nonprofity. La Stagione di Documenti Google sembrava interessante e le idee per i progetti di The Wikimedia Foundation hanno suscitato la mia curiosità, così ho iniziato a esplorare ulteriormente.

Finora il mio percorso è stato sempre stimolante e confusa, con frasi come "Aspetta, cosa?", "Ahh, ho capito!" e "Devo commentare questo?". La community di Wikimedia è stata incoraggiante in ogni fase. Dalla modifica delle pagine alla creazione delle estensioni, ogni giorno imparo qualcosa di nuovo.

Come previsto, il processo applicativo è stato il mio punto di accesso alla community open source. Questa proposta si ispira alle mie esperienze da principiante.

2. progetto

2.1. Contorno

Questo progetto mira a migliorare la documentazione per i tecnici e i potenziali videografi su Wikimedia. Una serie matura di linee guida sulla documentazione tecnica aiuterebbe a promuovere una documentazione complessiva migliore, mentre i riferimenti per la creazione di screencast consentirebbero una dimostrazione efficace delle funzionalità del software. La documentazione esistente in queste aree può essere estesa per supportare meglio sia i nuovi arrivati sia i collaboratori esperti. Verrà adottato un approccio incrementale per sviluppare questa rete di risorse pratiche.

2.2. Materiali da produrre

  • T197006 [https://phabricator.wikimedia.org/T197006]. Migliora 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 di documentazione tecnica: guide dell'utente, guide pratiche, guide rapide, note di rilascio e file README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Testa e migliora le linee guida per l'assegnazione delle priorità alla documentazione tecnica. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Elabora una strategia di raccolta dei 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 esaminare i propri documenti prima della pubblicazione.
    • Espandi la struttura della documentazione per i nuovi Technical Writer. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Prepara un elenco di attività di documentazione tecnica adatte agli hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Crea un hub per scrittori tecnici che indirizzi a risorse utili.

  • Migliora la documentazione per i videografi di MediaWiki:

    • Crea una guida rapida per l'utente per realizzare uno screencast generale.
    • Progetta modelli di screencast specifici per MediaWiki per procedure dettagliate e tutorial.

  • T214522 [https://phabricator.wikimedia.org/T214522]- Crea uno screencast "Introduction to Phabricator".

2.3. Obiettivo di stretching

  • Controlla di nuovo i contenuti e aggiorna la documentazione di WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentori

Zulip sarà il principale mezzo di comunicazione con i miei mentori. I canali e le email IRC di Wikimedia verranno utilizzati per le discussioni con la community. Le discussioni sulle 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 gli autori tecnici di Wikimedia.

In passato sono state intraprese diverse iniziative per migliorare la documentazione di MediaWiki con vari gradi di successo. Per citarne alcuni:

  • 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

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

Di seguito è riportato un estratto del report bisettimanale di uno stagista per il 2018 del Sociale, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

"La guida di stile di MediaWiki è tutt'altro che perfetta, tanto più che si basa troppo su riferimenti esterni senza evidenziare quali pratiche considera le migliori. Sfortunatamente, si tratta di un problema che non si limita unicamente a MediaWiki, in quanto compare in altra documentazione come le best practice per la traduzione. Gli scrittori finiscono per non disporre di risorse valide e affidabili per svolgere il proprio lavoro, il che porta a difficoltà nel definire un pubblico di destinazione e un adeguato stile di scrittura. Inoltre, gli utenti, in particolare i nuovi utenti, potrebbero riscontrare problemi per comprendere nuovi concetti e processi."

Inoltre, il documento T197006 [https://phabricator.wikimedia.org/T197006] fa luce su alcune aree della documentazione tecnica di scrittura che richiedono miglioramenti. Chiaramente, Documentazione/Guida_Stile è il punto di partenza.

Una volta che avremo una guida di stile migliore, verrà pianificata la successiva serie di documenti per guidare i Technical Writer nelle diverse fasi della scrittura tecnica. I documenti devono essere di livello principiante e allo stesso tempo fornire tutte le informazioni necessarie agli autori a cui fare riferimento.

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

Poi viene la fase di scrittura. Agli autori vengono forniti esempi di buon lavoro per alzare automaticamente il livello. Inoltre, viene creato un elenco di controllo con una serie di criteri di base che ogni documento deve rispettare, che aiuterà gli autori a rivedere i propri documenti prima della pubblicazione.

Nonostante questi documenti, i nuovi Technical Writer avranno bisogno di ulteriore assistenza, che noi dobbiamo dare loro. La guida per i nuovi Technical Writer viene perfezionata e viene fornito un elenco di attività adatte agli hackathon in base al livello di difficoltà.

Infine, viene testato e migliorato un documento per comprendere il processo di gestione e manutenzione della documentazione - "Assegnazione di priorità alla documentazione tecnica".

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

(ii) Creare modelli utili per i potenziali videografi.

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

Forse il modo migliore per imparare è quando ci si trova accanto a te da un esperto. Gli screencast si posizionano tra una grafica statica e un esperto a portata di mano. Riceviamo una demo visiva e commovente con una voce amichevole, possiamo anche inserire annotazioni di testo sullo schermo e animazioni. Il vantaggio degli screencast rispetto a quelli di un esperto è che possono essere rivisti a ogni ora di ogni giorno.

Possiamo anche aggiungere i sottotitoli tradotti a uno screencast in modo che possano essere visualizzati da persone che non siano madrelingua oppure sostituire la traccia audio con altre lingue."

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

Analogamente ai modelli per i documenti, avere un modello standard per gli screencast favorisce l'uniformità, migliorando così l'esperienza dello spettatore. Fornisce inoltre ai potenziali videografi un framework per iniziare. Pertanto, viene sviluppata una guida rapida per l'utente seguita da modelli per creare video introduttivi e tutorial. I documenti includono indicazioni sul livello di approfondimento dei concetti da trattare e alcune idee per screencast per MediaWiki.

Il modo migliore per testare il modello riportato sopra e prepararti all'obiettivo aggiuntivo è creare uno screencast utilizzando gli strumenti e i modelli. Viene quindi creato uno screencast di "Introduction to Phabricator" che illustra le nozioni di base dell'utilizzo di Phabricator. Questa procedura metterà in evidenza anche le aree che richiedono una discussione.

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

5. Sequenza temporale provvisoria

Periodo di obbligazioni della comunità (1° agosto - 1° settembre)

  • Analizzare il progetto in modo dettagliato con i miei mentori.

  • Discuti di:

    • La frequenza con cui devono essere riviste le attività.
    • Condividi le pianificazioni e decidi un flusso di lavoro settimanale o giornaliero.
    • Strumenti e risorse che possono essere utilizzati.
    • Report bisettimanali e giornalieri sul progetto.

  • Crea le attività secondarie richieste su Phabricator.

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

Settimana 1 (2-8 settembre)

  • Migliora la documentazione/guida_Stile:

    • Sposta l'attenzione per illustrare le best practice e gli standard su MediaWiki.
    • Includi esempi di buon lavoro e migliora la visibilità delle pagine associate.

  • Migliora la guida per i nuovi Technical Writer:

    • Espandi la struttura della documentazione.

Settimana 2 (9-15 settembre)

  • Lavorare sulla priorità della documentazione tecnica:

    • Valuta la scheda di lavoro della documentazione e trova esempi di descrizioni delle attività e di assegnazione delle priorità efficaci.
    • Studia le tendenze e annota le difficoltà comuni.
    • Utilizza le informazioni e gli esempi per documentare gli standard di priorità.

Settimana 3 (16 - 22 settembre)

  • Crea la seguente documentazione aggiuntiva per i Technical Writer:

    • Un elenco di controllo per semplificare la revisione della documentazione tecnica prima della pubblicazione.
    • Modi per raccogliere contenuti in modo efficace per diversi generi di documentazione.

Settimana 4 (23 - 29 settembre)

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

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

  • Aggiungere indicazioni per migliorare il livello di 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 dei nuovi collaboratori:

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

  • Crea un hub di Technical Writer

    • Crea una pagina di destinazione con link a pagine e risorse utili.
    • Aggiungi i link necessari alle pagine nuove ed esistenti per facilitare la navigazione tra le pagine.

Settimana 6 (7-13 ottobre)

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

    • Una guida rapida per l'utente sulla "creazione di uno screencast generale" che rimandi al progetto Registra schermo.
    • Modelli per: procedure dettagliate sull'utilizzo di un software/strumento; tutorial sullo sviluppo di nuovi strumenti.

  • Crea un elenco di idee per screencast per MediaWiki.

Settimana 7 (14-20 ottobre)

  • Lavora sul video "Introduction to Phabricator":

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

Settimana 8 (21-27 ottobre)

  • Pubblica il video "Introduction to Phabricator":

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

Settimana 9 (28 ottobre - 3 novembre)

  • Impegnati per migliorare la documentazione del progetto Registra schermo:

    • Esamina la struttura e discuti la necessità di apportare modifiche.
    • Esamina i software menzionati.
    • Cerca e aggiorna l'elenco dei software.

Settimana 10 (4 - 10 novembre)

  • Continua a migliorare la documentazione relativa al progetto Registra schermo:

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

Settimana 11 (11 - 17 novembre)

  • Completa la documentazione relativa al progetto Registra schermo:

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

Settimana 12 (18 - 24 novembre)

  • Lavora sulle attività in sospeso.

  • Scrivi il report finale:

    • Consultare i report bisettimanali/giornalieri e raccogliere le informazioni richieste.
    • Pianifica la struttura del report e scrivi una bozza.
    • Migliora e finalizza la bozza in base al feedback del tutor.

Settimana 13 (25 - 29 novembre)

  • Invia il report finale e la valutazione del mentore.

6. Monitoraggio dei progressi

Gli aggiornamenti giornalieri sui progressi verranno comunicati ai miei mentori su Zulip. La community di Wikimedia può monitorare i miei progressi tramite Phabricator o tramite i rapporti bisettimanali sul progetto.

7. Altri impegni

Sono uno studente universitario a tempo pieno e il mio semestre accademico autunnale si sovrappone alla sequenza temporale della stagione dei documenti. Di conseguenza, 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

Prevedo anche di partecipare alla mia prima conferenza pubblica, PyCon India, dal 12 al 15 ottobre, grazie alla posizione favorevole di quest'anno. Credo che sarebbe una grande opportunità per incontrare nuove persone e avere conversazioni costruttive.

Per gestire questi impegni, la tempistica provvisoria contiene attività meno pesanti nelle settimane corrispondenti. Intendo completare non più di 20 crediti di base nel semestre autunnale per avere tempo sufficiente per lo sviluppo dei documenti. (Uno studente regolare completa 25 crediti in media per semestre)