Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Matplotlib
- Technical writer:
- Jeromev
- Nome progetto:
- Sviluppo dei percorsi di voce in Matplotlib
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Introduzione
Il suggerimento di progetto di Matplotlib per la stagione dei documenti Google di quest'anno prevede la creazione di contenuti che aiutino a presentarlo ai nuovi utenti. Per lo sviluppo di percorsi di voce in Matplotlib, propongo un approccio alternativo a quello della documentazione attuale. Sono un nuovo Technical Writer nel settore, ma la mia formazione in campi correlati all'istruzione e all'istruzione. La scrittura tecnica e la formazione hanno forti analoghi che si concentrano sulla produzione di contenuti che creino empatia e consentano agli utenti di svolgere le loro attività con le risorse fornite.
In questo contesto, la documentazione di Matplotlib trarrebbe vantaggio da un miglioramento dell'empatia con i nuovi utenti. Gran parte del materiale al momento è costituito da dati casuali e immagini non etichettate. Sono eccellenti per mostrare rapidamente le immagini e le funzionalità di Matplotlib. Tuttavia, nel caso di una persona che non ha mai utilizzato Matplotlib, è difficile attraversare la trasformazione dei dati in immagini.
Un contesto in un approccio espositivo è una soluzione a questo ostacolo. Scrivendo una procedura attraverso la lente di un esempio reale, stiamo dimostrando una comprensione dell'ambiente in cui lavora un utente. Ciò migliora la relazione tra la documentazione e l'utente in termini di raggiungimento di un obiettivo o di aspettative rispetto al 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 navigare in Matplotlib e a utilizzare gli strumenti all'interno della libreria per completare l'attività in questione.
Grazie a 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 raggiungere la vision che il Lead Developer Tom Caswell ha discusso in un'intervista nel 2017 come "avere una persona che sia effettivamente in grado di scrivere ed abbia empatia nei confronti degli utenti, che esegua e sostanzialmente scriva un libro di 200 pagine dal titolo "Intro to Matplotlib" e che questa sia la voce principale della documentazione."
Approccio alternativo alla scrittura di espositori
La documentazione attuale dimostra le funzionalità di Matplotlib, ovvero le cose che un utente è in grado di fare con la libreria. Ad esempio, un tutorial spesso segue un pattern che non prevede una spiegazione del metodo sottostante.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Spesso all'interno della documentazione e dell'assistenza per la programmazione, si consiglia all'utente di eseguire il codice autonomamente per capire cosa succede. Sebbene una mentalità di programmazione migliori la comprensione dell'argomento da parte degli utenti, la curva di apprendimento per le trasformazioni ha pochi contenuti di supporto. Può essere un'impresa ardua poiché la documentazione è limitata.
Fornire diagrammi, immagini o altri elementi visivi aggiuntivi contribuirà a creare nuove opportunità di apprendimento. La seguente struttura funge anche da modello per i nuovi contenuti. Inoltre, l'aggiunta di immagini o grafici non testuali può trarre vantaggio da funzionalità come callout e coachmark. Ci sono casi in cui la navigazione nelle immagini è più difficile senza indicazioni su come o dove il codice viene trasformato nell'output eseguito. Credo che manchi un forte elemento visivo che potrebbe 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 per la documentazione. Se gli utenti vedono una varietà di concetti per le trasformazioni, potrebbero identificare meglio le strategie sottostanti per lo sviluppo di visualizzazioni dei dati. Queste conoscenze possono aiutare gli utenti a innovare e sfruttare le funzionalità presentate da esempi basati su casi d'uso realistici.
Man mano che Matplotlib cresce in popolarità, la semplicità d'uso e l'accoglienza costante sono una prova della reputazione della raccolta. Queste caratteristiche si prestano a dimostrare pattern e strategie comuni che possono emergere non solo all'interno del codice, ma anche all'interno della documentazione. Se Matplotlib è semplice e standard da programmare, come si vede dal suo utilizzo crescente e dall'espansione delle risorse, può esserlo anche per la documentazione tecnica.
Quando gli utenti riscontrano problemi, è comune utilizzare la ricerca per risolverli. Anziché affidarsi alla ricerca come metodo principale di navigazione, può essere più efficace fare in modo che gli utenti creino il proprio programma all'interno della documentazione. In questo caso, un utente cerca una soluzione al proprio problema, quindi, quando riscontra un altro problema o desidera ulteriori informazioni, utilizza link incorporati e completi.
Ciò implicherebbe un'architettura dal basso verso l'alto nel sistema organizzativo. Per ogni argomento di Matplotlib, una ricca rete di link alle affinità degli argomenti e ad argomenti informativi contribuirebbe a creare una solida rete. All'interno di questa rete, è più probabile che gli utenti continuino a utilizzare la documentazione mentre consultano il proprio argomento ed esplorano sempre più informazioni correlate a quell'argomento.
Ostacoli
Un progetto così completo e dettagliato come questo comporta sempre delle sfide. In qualità di nuovo Technical Writer nel settore, ho poca esperienza nell'uso di Sphinx e ReST per scrivere documentazione. Sono anche alle prime armi con Matplotlib e Git. Affrontare questi quattro sistemi e acquisire familiarità con l'utilizzo per la collaborazione e la ricerca richiederà tempo. Dovrò delegare del tempo durante la fase di community bonding e prima per costruire le basi necessarie per i percorsi di livello base. Durante questo periodo, in caso di problemi con concetti e concetti fondamentali, dovrò contattare la community per ricevere ulteriore assistenza.
Anche il coordinamento degli sforzi di collaborazione tra fusi orari e piattaforme online richiederà alcune modifiche. Le persone che operano nel settore utilizzano una varietà di canali di comunicazione, quindi è necessario assicurarmi di essere accessibile e accessibile con tutti i mezzi. In questo modo, assegnerò in modo trasparente la priorità alle variazioni delle aspettative. Anche se sono solo all'inizio di un lavoro come questo nel settore, sono impegnato a rendermi responsabile ed essere disponibile a ricevere feedback e critiche. Ritengo che queste qualità siano preziose, indipendentemente dal campo.
Inoltre, l'aumento dei test di usabilità è una sezione della documentazione che credo apporterebbe vantaggi ai percorsi di ingresso di Matplotlib. La conduzione di sondaggi per verificare l'usabilità dei contenuti ha lo scopo di creare un profilo di un utente, ad esempio gli utenti tipo. Informazioni quali l'esperienza utente, il settore in cui opera e la cronologia della risoluzione dei problemi sono importanti. Questi contenuti aiutano a definire il linguaggio su cui si basa la procedura. Quando la scrittura si avvicina ai lettori del loro livello, i contenuti maturano e vanno oltre la semplice funzione didattica.
Le grandi difficoltà spesso riguardano la creazione di una pratica continua di test dell'usabilità. È fin troppo comune avere una singola istanza di test, se eseguita, durante lo sviluppo dei contenuti. I test regolari di usabilità contribuiscono a sviluppare la narrazione dei contenuti. Spero di poter programmare un appuntamento o di effettuare test di usabilità ricorrenti con la community di Matplotlib.
Conclusione
Ho un po' di esperienza con Python e Matplotlib nel tempo libero. Ho imparato da solo negli ultimi mesi grazie al supporto della documentazione attuale e alla 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ù margini di miglioramento man mano che creo il mio curriculum di programmazione che mi interessa.
Dopo aver visto le idee che Matplotlib e la community hanno su GSoD, ritengo che sarebbe un'ottima esperienza di crescita per migliorare le mie competenze di Technical Writer e avere la possibilità di imparare di più dalle persone dietro le quinte. Ho sentito che questo progetto in Matplotlib è significativo e allo stesso tempo è un argomento che mi appassiona per quanto riguarda l'ideologia.
Per aver lavorato alla revisione della guida all'uso, il mio obiettivo in qualità di Technical Writer è aiutare gli utenti a svolgere le attività che vogliono senza essere sopraffatti dalle funzionalità disponibili. Credo che la migliore documentazione continuerà a crescere, adattarsi agli utenti e consentire a qualsiasi utente di accedere alle proprie soluzioni.