Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- Matplotlib
- Technical Writer:
- jeromev
- Nome del progetto:
- Sviluppare percorsi di accesso Matplotlib
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Introduzione
Il suggerimento di Matplotlib per la stagione di Documenti Google di quest'anno prevede la creazione di contenuti che aiutino a presentare Matplotlib ai nuovi utenti. Per lo sviluppo di percorsi di accesso Matplotlib, propongo un approccio alternativo a quello della documentazione attuale. Sono un nuovo Technical Writer nel settore, ma ho un background nell'istruzione e in campi correlati. La scrittura tecnica e la didattica hanno forti parallelismi che si concentrano sulla produzione di contenuti che mettano in relazione gli utenti e li aiutino a svolgere le loro attività con le risorse fornite.
In questo contesto, la documentazione di Matplotlib potrebbe trarre vantaggio dal miglioramento dell'empatia con i nuovi utenti. Al momento, gran parte del materiale è costituito da dati casuali e immagini non etichettate. Sono ottimi per visualizzare rapidamente le visualizzazioni e le funzionalità di Matplotlib. Tuttavia, per chi non ha dimestichezza con Matplotlib, è difficile gestire la trasformazione dei dati in elementi visivi.
Un contesto in un approccio espositivo è una soluzione a questo ostacolo. Scrivendo una procedura dalla lente di un esempio reale, dimostriamo di comprendere l'ambiente in cui lavora un utente. Ciò migliora la relazione tra la documentazione e l'utente in termini di raggiungimento di un obiettivo o aspettativa di completamento di un'attività.
Un utente ha uno scopo derivato coerente. Ad esempio, un data scientist di un'azienda di calzature deve presentare i dati dei clienti a un team per illustrare le tendenze di acquisto nel tempo. In questa situazione, l'utente deve imparare a utilizzare Matplotlib e sfruttare gli strumenti all'interno della libreria per completare l'attività in questione.
Con un contesto aggiuntivo a supporto della documentazione, un nuovo utente potrebbe essere più in grado di identificarsi con l'argomento. Lo scopo derivato dell'utente è parallelo alla documentazione. Spero di poter lavorare per la vision di cui il Lead Developer Tom Caswell ha discusso in un'intervista nel 2017 come "avere qualcuno che sia in grado di scrivere ed abbia empatia nei confronti degli utenti, che vogliano scrivere un'introduzione a Matplotlib di 200 pagine, che sia l'elemento principale dei documenti".
Approccio alternativo alla scrittura di esposizioni
La documentazione attuale mostra le funzionalità di Matplotlib, ovvero le operazioni che un utente può eseguire con la libreria. Ad esempio, un tutorial spesso segue uno schema che non prevede una spiegazione del metodo sottostante.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Spesso, con la documentazione e l'assistenza per la programmazione, agli utenti viene consigliato di eseguire il codice in autonomia per capire cosa succede. Sebbene un approccio alla programmazione migliori la comprensione dell'argomento da parte dell'utente, la curva di apprendimento delle trasformazioni offre pochi contenuti di supporto. Può essere una sfida scoraggiante perché la documentazione è limitata.
Fornire ulteriori diagrammi, immagini o altri elementi visivi contribuirà a creare nuove opportunità di apprendimento. La struttura riportata di seguito può essere utilizzata anche come modello per i nuovi contenuti. Inoltre, l'aggiunta di immagini o grafici non di testo potrebbe trarre vantaggio da funzionalità come callout e indicatori. A volte è più difficile navigare nelle immagini senza indicazioni su come o dove il codice viene trasformato nell'output eseguito. Credo che manchi un elemento visivo efficace che possa favorire una maggiore comprensione degli argomenti.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Questo approccio alternativo offre un enorme potenziale all'utilizzo della scrittura espositiva a scopo di documentazione. Avendo visto una varietà di concetti per le trasformazioni, gli utenti sarebbero in grado di identificare meglio le strategie di base per lo sviluppo delle visualizzazioni dei dati. Queste conoscenze possono aiutare gli utenti a innovare e sfruttare le funzionalità come mostrato dagli esempi basati su casi d'uso realistici.
Con l'aumento della popolarità di Matplotlib, la coerenza in termini di facilità d'uso e accessibilità sono la prova della reputazione della libreria. Queste caratteristiche si prestano a dimostrare modelli e strategie comuni che possono essere visualizzati non solo nel codice, ma anche nella documentazione. Se Matplotlib è semplice e standard per la programmazione da parte degli utenti, come è evidente dal suo utilizzo crescente e dall'espansione delle risorse, può esserlo anche per la documentazione tecnica.
Quando gli utenti riscontrano problemi, è normale che ricorrano alla ricerca per risolverli. Anziché fare affidamento sulla ricerca come metodo principale di navigazione, può essere più efficace consentire agli utenti di creare il proprio programma all'interno della documentazione. In questo senso, un utente cerca una soluzione al suo problema, poi, quando si imbatte in un altro problema o vuole ulteriori informazioni, utilizza i link incorporati e dettagliati.
Ciò comporterebbe un'architettura dal basso verso l'alto nel sistema organizzativo. Per ogni argomento all'interno di Matplotlib, una ricca rete di link alle affinità degli argomenti e agli argomenti informativi contribuirebbe a creare una rete solida. In tutta questa rete, è più probabile che un utente continui a utilizzare la documentazione mentre esplora un argomento ed esplora sempre più informazioni correlate.
Ostacoli
Un progetto così completo e dettagliato come questo presenta sempre delle sfide. Essendo un nuovo Technical Writer nel settore, ho un'esperienza limitata nell'utilizzo di Sphinx e ReST per scrivere la documentazione. Sono anche un principiante per quanto riguarda Matplotlib e Git. Imparare a utilizzare questi quattro sistemi per la collaborazione e la ricerca richiede tempo. Dovrò dedicare del tempo alla fase di creazione di un legame con la community e a quella precedente per creare le basi necessarie per i percorsi di livello base. Durante questo periodo, se ho problemi con i concetti e le nozioni di base, dovrò contattare la community per ulteriore assistenza.
Anche il coordinamento delle attività di collaborazione tra fusi orari e piattaforme online richiederà alcuni aggiustamenti. Esistono diversi canali di comunicazione utilizzati dalle persone in tutto il settore, quindi è importante assicurarsi di essere accessibile e disponibile su tutti i mezzi. Sarò trasparente nella definizione delle priorità delle varie aspettative. Anche se ho appena iniziato a occuparmi di un lavoro come questo nel settore, voglio dedicarmi a essere responsabile e disponibile a ricevere feedback e critiche. Ritengo che queste qualità siano importanti indipendentemente dal campo.
Inoltre, l'aumento dei test di usabilità è una sezione della documentazione che ritengo possa essere utile per i percorsi di accesso di Matplotlib. Condurre sondaggi sull'usabilità dei contenuti ha lo scopo di fornire un profilo dell'utente, ovvero delle persone. Sono importanti informazioni come l'esperienza di un utente, il settore in cui lavora e la cronologia della risoluzione dei problemi. Questi elementi contribuiscono a formare il linguaggio alla base della procedura. Quando la scrittura incontra i lettori al loro livello, i contenuti maturano e non servono più solo come materiale didattico.
I problemi più grandi spesso riguardano la creazione di una pratica continua di test di usabilità. È fin troppo comune che durante lo sviluppo dei contenuti sia stata eseguita una singola istanza di test, se non è stato eseguito alcun test. I test di usabilità regolari aiutano a migliorare la narrazione dei contenuti. Mi piacerebbe impostare una pianificazione o eseguire test di usabilità ricorrenti con la community di Matplotlib.
Conclusione
Ho un po' di esperienza nell'uso di Python e Matplotlib nel mio tempo libero. Le lezioni che ho imparato da me negli ultimi mesi sono state il sostegno della documentazione attuale e la mia curiosità. C'erano anche una manciata di video e mentori che ho avuto in quel periodo. Ho ancora molto da imparare e ancora più spazio di miglioramento mentre creo il mio programma di studi di programmazione che mi interessa.
Dopo aver visto le idee di Matplotlib e della community per GSoD, ho pensato che sarebbe un'esperienza di crescita eccellente per migliorare le mie competenze di scrittore tecnico e avere la possibilità di imparare di più dalle persone dietro le quinte. Ho ritenuto che questo progetto Matplotlib sia significativo e che mi appassiona per ideologia.
Dato che sto lavorando a una revisione della guida all'utilizzo, il mio obiettivo come autore tecnico è aiutare gli utenti a svolgere le attività che vogliono senza essere sopraffatti dalle funzionalità disponibili. Credo che la documentazione migliore debba continuare a crescere e adeguarsi agli utenti, consentendo a chiunque di trovare le proprie soluzioni.