Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- NumPy
- Technical Writer:
- cooperrc
- Nome del progetto:
- Documentazione di NumPy per la formazione della community
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Introduzione
NumPy offre un calcolo basato su array pulito e veloce in una libreria software open source senza costi. È un pacchetto fondamentale nello stack SciPy per il calcolo scientifico [1]. Più di 370 mila progetti lo utilizzano per un calcolo di array efficiente [2]. Gli utenti di NumPy vengono accolti da un nuovo sito web con applicazioni e case study [1]. Quando un nuovo utente trova la pagina della documentazione, si trova di fronte a diversi link "Inizia qui" e tutorial introduttivi che possono essere travolgenti per un principiante, come Nozioni di base su NumPy/scambio di byte. Ho iniziato a utilizzare NumPy dieci anni fa durante la scuola di specializzazione. Mi sono ritrovata a mettere insieme post del blog, appunti sulle lezioni e risposte di StackExchange per evitare di esaminare la documentazione di NumPy. Al momento esistono oltre 360.000 conversazioni su StackExchange che trattano di NumPy. Immagino che altri utenti abbiano avuto percorsi simili verso il successo in NumPy. I componenti di base degli strumenti didattici sono la comunicazione e la community [4]. La documentazione deve creare una community che rifletta gli obiettivi del progetto. La documentazione deve essere una guida coerente e chiara per un nuovo utente. I tutorial devono fornire ai nuovi utenti una procedura facile da seguire e aiutarli a familiarizzare con la raccolta [3]. La documentazione dovrebbe dare il benvenuto a un nuovo utente nella community di NumPy. La struttura, il ritmo e gli autori della documentazione devono creare un luogo che incoraggi l'esplorazione e la comunicazione. Questa proposta organizzerà e colmerà le lacune nell'attuale documentazione di NumPy in modo che i nuovi utenti vengano istruiti e accolti nella community.
Le conoscenze comunicate dagli utenti vengono acquisite tramite test e sperimentazioni [4,5]. Le conoscenze dipendono dal metodo di test e valutazione. I contenuti che forniscono scopi e applicazioni chiari nelle istruzioni consentono agli utenti di testare e valutare nuove idee e metodi. La community può creare una knowledge base per migliorare competenze, fatti e applicazioni. Lo spazio dedicato alle istruzioni offre un duplice vantaggio. Innanzitutto, gli utenti nuovi ed esperti hanno una serie di obiettivi chiari per testare e creare esperimenti. In secondo luogo, i potenziali collaboratori alla documentazione hanno uno spazio per comunicare i propri obiettivi, metodi e soluzioni. La sezione How-to soddisfa un'esigenza immediata di rendere la documentazione di NumPy più accessibile per i nuovi utenti e i potenziali collaboratori. Conoscenze attuali
John Dewey diceva che la base dell'apprendimento è un'esperienza autentica [4]. La community di NumPy ha un'enorme quantità di esperienze spontanee che possono essere condivise con altri utenti. L'istruzione si basa sulla comunità e sulla comunicazione. Una pagina di documentazione organizzata spianerà la strada ai nuovi utenti per provare NumPy. Inoltre, crea un modello strutturato che consenta ai potenziali collaboratori di comunicare le loro esperienze in NumPy.
Esistono quattro spazi raggruppati in modo generico per la documentazione del software [3]: spazio dei tutorial, spazio dei tutorial, spazio delle spiegazioni e spazio di riferimento. La documentazione di NumPy contiene una serie di documenti nello spazio dei tutorial che combinano spiegazioni e contenuti dello spazio dei tutorial. Lo spazio del tutorial deve concentrarsi sull'istruzione degli utenti e utilizzare passaggi facili da ripetere per comunicare le idee. Lo spazio didattico offre procedure più orientate agli obiettivi che gli utenti possono applicare nelle applicazioni del mondo reale. Lo spazio di spiegazione fornisce informazioni dettagliate sulle stringhe di documenti in ogni funzione. Gli attuali spazi di tutorial e istruzioni non sono chiaramente delineati e a volte interferiscono con lo spazio di spiegazione e riferimento. Esiste un tutorial eccellente per principianti assoluti e un'ottima risorsa per gli utenti di Matlab per creare codice NumPy in "Numpy per gli utenti di Matlab". La definizione chiara di questi quattro spazi rende la documentazione più chiara.
Mancata corrispondenza nella Knowledge Base/Necessità non soddisfatta
La documentazione attuale tratta molti argomenti necessari, ma manca una chiara distinzione tra tutorial, istruzioni, spiegazioni e spazi di riferimento. Ciò crea confusione per i potenziali collaboratori. I nuovi utenti possono essere sopraffatti dalle spiegazioni e dal materiale di riferimento nella sezione del tutorial e i potenziali collaboratori devono affrontare ostacoli per dare il proprio contributo. Propongo un layout più accessibile per i neofiti e i possibili collaboratori alla documentazione, con un flusso logico nella documentazione e la gestione delle richieste pull per i documenti di istruzioni condivisi dagli utenti da parte dei nuovi collaboratori. Il mio obiettivo a lungo termine è costruire la community della documentazione in modo che imparare dalla documentazione sia un'esperienza di scambio e di formazione. Questo modello di documentazione baserà l'insegnamento sull'esperienza reale per i nuovi arrivati e i potenziali collaboratori.
Motivazione
Questa proposta di Google Summer of Docs è importante per i miei obiettivi pedagogici e di carriera. Utilizzo NumPy e SciPy in tutti i miei corsi. Per i miei studenti è difficile consultare la documentazione attuale. Voglio utilizzare la mia esperienza nell'insegnamento del codice a studenti non di informatica per contribuire a organizzare, modificare e colmare le lacune dei tutorial attuali. Poi posso utilizzare la documentazione come libro di testo e materiale di riferimento per i miei corsi. Ho creato dozzine di tutorial, esercizi ed esempi utilizzando Python e
Scopi specifici
Ho tre obiettivi specifici per questa proposta di Google Summer of Docs: 1. Organizza la documentazione attuale. Modifica i tutorial attuali (Guida per principianti, Creazione di array, Indicizzazione, Algebra lineare e NumPy per Matlab) per spostare le informazioni di riferimento nello spazio di spiegazione e 3. Creare materiali di istruzioni con gli studenti. Ogni scopo specifico ha un risultato previsto per la proposta.
Questi tre obiettivi specifici hanno lo scopo di rendere la documentazione più accogliente per i nuovi utenti e fornire una struttura per i potenziali collaboratori. Gli scopi contribuiscono anche a perseguire l'obiettivo a lungo termine di continuare a far crescere la community di documentazione di NumPy. Risultati previsti
Prevedo tre risultati: 1. Una pagina web della documentazione rivista che separa chiaramente i quattro spazi: tutorial, istruzioni, spiegazioni e riferimenti, 2. nuovi tutorial per: lettura e scrittura di array, creazione di array (np.zeros, np.ones, np.block e così via) e operazioni elementari rispetto all'algebra lineare in NumPy e 3. uno spazio di istruzioni selezionate.
Questi risultati previsti aiuteranno i nuovi utenti a comprendere meglio i documenti, forniranno ai potenziali collaboratori della documentazione stili e formati chiari, renderanno i tutorial attuali più brevi e facili da seguire, sposteranno le spiegazioni in una sezione separata e i nuovi collaboratori della documentazione potranno contribuire con piccoli casi d'uso alla sezione delle procedure senza dover creare l'intera documentazione di Sphinx. Vogliamo continuare a creare una community di insegnamento e apprendimento.
I nuovi collaboratori alla documentazione possono contribuire con piccoli casi d'uso a milioni di utenti senza dover creare l'intera documentazione di Sphinx. Vogliamo continuare a creare una community di insegnamento e apprendimento. La documentazione proposta rispecchierà la documentazione open source attuale, come Matplotlib, Divio e così via. I nuovi utenti e i potenziali collaboratori avranno più facilità ad apprendere come applicare NumPy nei loro campi e software.
Le tempistiche del progetto sono dal 14/09 al 30/11. Il primo passaggio consiste nel creare la documentazione e separare i contenuti dei tutorial attuali in tutorial, istruzioni e spiegazioni. Ciò avverrà nelle prime cinque settimane del progetto nell'ambito dei risultati 1 e 2, rispettivamente, relativi alla revisione del sito web e delle esercitazioni. L'organizzazione della documentazione proposta è riportata nella documentazione proposta di seguito.
Documentazione proposta:
i.Tutorials:
- Nozioni di base per principianti (rimuovere l'installazione, l'importazione/esportazione di pandas può essere sostituita con numpy.loadtxt?)
- link a "Che cos'è numpy"
- link alle istruzioni di installazione di base qui
- Tutorial di avvio rapido (pensato come seguito del tutorial di Python)
- Lavorare con gli array NumPy
- creazione di array (np.zeros, np.ones, np.block e così via) (scrittura: priorità media-bassa)
- Operazioni elementari (+,-,*,/) e operazioni di algebra lineare (+,-,@, linalg.solve) (priorità scrittura:media)
- Leggere e scrivere dati utilizzando Numpy (scrittura: priorità alta)
- Indicizzazione
ii. Istruzioni:
- Algebra lineare su array n-dimensionali (mi piacerebbe modificare le intestazioni e le descrizioni e magari cambiare il titolo in "Elaborazione di immagini con l'algebra lineare di Numpy")
- link ai contenuti di istruzioni di numpy-tutorials (lavoro in corso)
iii. Spiegazione:
- Tipi di dati
- I/O con Numpy
- Indicizzazione
- Trasmissione
- Cambio byte
- Array strutturati
- Scrittura di container di array personalizzati
- sottoclassamento ndarray
- Varie
iv. Spazio di riferimento:
- Glossario
- Riferimento API Numpy
- Numpy per gli utenti di Matlab (la tabella di equivalenza è un'ottima tabella di riferimento, ma la discussione su array/matrici è fonte di distrazione e sembra deprecata)
Al termine di questa stagione di Documenti Google, propongo i seguenti risultati:
- Una pagina web della documentazione aggiornata che separa chiaramente i quattro spazi: Tutorial, Istruzioni, Spiegazione e Riferimenti
- Nuovi tutorial per: creazione di array (np.zeros, np.ones, np.block e così via), operazioni elementari (+, -,*,/) e operazioni di algebra lineare (+, -,@, linalg.solve) e lettura e scrittura di dati utilizzando Numpy (alta priorità)
- Documenti di istruzioni consigliati per aumentare i contributi degli utenti e contribuire a raggiungere gli obiettivi della community nell'insegnamento e nell'apprendimento
Ogni esito prevede una serie di passaggi descritti di seguito nelle tabelle relative agli esiti 1-3. Mentre la documentazione proposta viene inviata per la revisione, il tutorial ad alta priorità "Lettura/scrittura array" verrà scritto per l'invio come richiesta di pull nell'ambito del Risultato 2. Durante la revisione del sito web aggiornato e del tutorial "Array di lettura/scrittura", inizierò a scrivere un tutorial per la creazione di array utilizzando le funzioni NumPy, ad esempio np.ones, np.zeros, np.diag. Il tempo rimanente verrà utilizzato per rispondere ai problemi relativi alle richieste pull e per iniziare a scrivere il tutorial di livello 3: Operazioni elementari e di algebra lineare in Python.
Il terzo risultato è consigliare agli studenti dell'Università del Connecticut di creare la documentazione nel repository numpy-tutorials. I tutorial o i documenti di istruzioni inviati saranno blocchi Jupyter che utilizzano NumPy per risolvere problemi di ingegneria. Utilizzerò alcune delle mie note/esempi del corso per inviare un notebook di esempio. Consiglierò agli studenti di seguire il layout e la struttura durante la creazione di un modello e di uno schema di inquadratura. Questo risultato offre agli studenti un'esperienza autentica per comunicare concetti e soluzioni a un pubblico più ampio. È un'ottima opportunità per gli studenti di interagire con la community di NumPy e imparare.
Risultato 1: revisione del sito web Deliverable Date Repository di fork e creazione di documenti con Sphinx 9/21 Crea pagina web con quattro spazi definiti e collegati 10/1 Sposta i tutorial attuali negli spazi appropriati e crea documenti 10/10 Invia PR a GitHub con le modifiche proposte 11/1 Rispondi a commenti/suggerimenti rivisti e rivedi il PR in corso con 1 Risultato 1
Risultato 2: rivedi i tutorial Data di consegna Revisione del ranking dei tutorial 9/21 Separa i contenuti attuali dei tutorial negli spazi Tutorial ed Esplicazione 10/1 Scrivi il ranking 1: array di lettura/scrittura 10/10 Invia la richiesta di pull a GitHub per la separazione e la revisione 10/20 Scrivi il ranking 2: richiesta di pull per la creazione di array 11/15 Scrivi il ranking 3: richiesta di pull per le operazioni elementari e di algebra lineare 11/30
Ranking proposto per le revisioni dei tutorial (soggette a variazioni in base ai tutor/alla community):
Pagina degli array di lettura/scrittura attualmente vuota
Creazione di array (np.zeros, np.ones, np.block, ecc.) Non esiste: aiuterebbe i nuovi utenti a spiegare e dimostrare gli strumenti comuni per la creazione/interazione di array
Operazioni elementari e di algebra lineare (+,-,*,/ e +,-@,linalg.solve) Non esistono: questo è particolarmente utile per 1. Utenti di Matlab e 2. Persone che adottano l'algebra lineare (machine learning, regressione lineare ecc.)
Risultato 3: spazio di istruzioni selezionate Data di consegna Link esterno(problema/esempio)
Creare un esempio di istruzioni (candidato: come trovare le frequenze naturali delle corde della chitarra 10/20
Creare un modello di istruzioni per i nuovi collaboratori 10/1 in corso Modello di tutorial PR e inquadramento dei possibili contributi
Collaborare con altri collaboratori per creare notebook di istruzioni per il reclutamento di studenti dell'Università del Connecticut e di altri membri della community Stato del 7/1: programma di lavoro-studio approvato e richieste in arrivo
Significato previsto
Questa proposta di Google Summer of Docs migliorerà la documentazione di NumPy, completerà i tutorial mancanti del sito web e acquisirà collaboratori per la documentazione. In qualità di professore di ingegneria meccanica, ho intenzione di suddividere la documentazione in modo che i miei studenti possano navigare tra i documenti e trovare facilmente tutorial introduttivi e guide pratiche. La documentazione segmentata: tutorial, istruzioni, riferimenti e spiegazioni fornirà ai potenziali collaboratori esempi strutturati per creare nuove risorse. La documentazione proposta si presta a un confronto attraverso un'esperienza formativa e comunicativa per utenti nuovi ed esperti. La proposta di consulenza sui documenti didattici con gli studenti della University of Connecticut metterà in pratica questa idea istruttiva e comunicativa. Vogliamo che tutti gli utenti abbiano la possibilità di sperimentare, imparare e partecipare alla community di NumPy.
Riferimenti
- Accesso al sito web NumPy.org a luglio 2020.
- Repository GitHub di NumPy.
- il sistema di documentazione. Accesso a Divio.com il 07/2020.
- Dewey, John. Democrazia e istruzione. Project Gutenberg, agosto 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.