Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- NumPy
- Technical writer:
- cooperrc
- Nome progetto:
- Documentazione di NumPy per l'istruzione della community
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Introduzione
NumPy offre un'elaborazione basata su array veloce e pulita in una libreria software open source senza costi. È un pacchetto fondamentale nello stack SciPy per il calcolo scientifico [1]. Oltre 370.000 progetti utilizzano l'efficiente calcolo di un array [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, viene incontro a più link "Inizia da qui" e tutorial introduttivi che possono essere difficoltosi per un principiante, come le nozioni di base di NumPy/lo scambio di byte. Ho iniziato a usare NumPy dieci anni fa in una scuola di specializzazione. Mi sono ritrovata a mettere insieme post di blog, appunti sulle lezioni e risposte di StackExchange per evitare di consultare la documentazione di NumPy. Attualmente esistono oltre 360.000 conversazioni StackExchange che riguardano NumPy. Immagino che altri utenti abbiano seguito percorsi simili verso il successo in NumPy. Gli elementi fondamentali degli strumenti didattici sono la comunicazione e la comunità [4]. La documentazione deve creare una community che rifletta gli obiettivi auspicati del progetto. La documentazione deve essere una guida chiara e coerente per i nuovi utenti. I tutorial dovrebbero fornire ai nuovi utenti passaggi facili da seguire e acquisire dimestichezza con la libreria [3]. La documentazione deve dare il benvenuto a un nuovo utente nella community di NumPy. La struttura, il ritmo e gli autori della documentazione devono tutti creare un luogo che accoglie l'esplorazione e la comunicazione. Questa proposta organizzerà e colma le lacune nella documentazione corrente di NumPy in modo che i nuovi utenti vengano istruiti e accolti nella community.
Le conoscenze che gli utenti comunicano si acquisiscono testando e sperimentando [4,5]. La conoscenza dipende dal metodo di verifica e valutazione. I contenuti che forniscono istruzioni e obiettivi chiari e pratici permettono agli utenti di testare e valutare nuove idee e metodi. La community può costruire una knowledge base per migliorare competenze, fatti e applicazioni. Lo spazio di istruzioni offre un duplice vantaggio. In primo luogo, gli utenti nuovi ed esperti hanno una serie di obiettivi chiari da testare e creare esperimenti. In secondo luogo, i potenziali collaboratori alla documentazione hanno uno spazio in cui comunicare i propri obiettivi, metodi e soluzioni. Lo spazio di istruzioni risponde a un'esigenza immediata di rendere la documentazione di NumPy più accessibile a nuovi utenti e possibili collaboratori. Conoscenze attuali
John Dewey ha affermato che la base dell'apprendimento è un'esperienza autentica [4]. La community di NumPy ha un'enorme quantità di esperienza autentica che può essere condivisa con altri utenti. L'istruzione si basa sulla comunità e sulla comunicazione. Una pagina di documentazione organizzata apre la strada ai nuovi utenti per sperimentare NumPy. Inoltre, crea un modello strutturato per consentire ai potenziali collaboratori di comunicare le proprie esperienze in NumPy.
Esistono quattro spazi raggruppati in modo ampio per la documentazione del software [3]: spazio tutorial, spazio per le istruzioni, spazio per la spiegazione e spazio di riferimento. La documentazione di NumPy contiene una serie di documenti nello spazio del tutorial che combinano spiegazioni e istruzioni per inserire contenuti nel tutorial. Lo spazio dei tutorial deve essere incentrato sulla formazione degli utenti e utilizza passaggi facili da ripetere per comunicare le idee. Lo spazio di istruzioni offre procedure più orientate agli obiettivi che gli utenti possono applicare nelle applicazioni reali. Lo spazio di spiegazione fornisce informazioni dettagliate sulle stringhe dei documenti in ogni funzione. Gli spazi del tutorial attuale e delle istruzioni non sono chiaramente definiti e a volte vengono inseriti nella spiegazione e nello spazio di riferimento. C'è un eccellente tutorial per il "principiante assoluto" e c'è un ottimo riferimento per gli utenti Matlab per la creazione di codice NumPy in "Numpy per gli utenti Matlab". La descrizione chiara di questi quattro spazi rende la documentazione più chiara.
Lacune nella knowledge base/necessità insoddisfatta
La documentazione attuale tratta molti argomenti necessari, ma non distingue in modo chiaro tra tutorial, istruzioni, spiegazioni e spazi di riferimento. Questo crea confusione nei potenziali collaboratori. I nuovi utenti possono essere sommersi da spiegazioni e materiale di riferimento nella sezione del tutorial e i potenziali collaboratori devono affrontare ostacoli. Propongo un layout più accessibile per i nuovi arrivati e i possibili collaboratori con un flusso logico nella documentazione e la gestione delle richieste di pull per i documenti didattici forniti dagli utenti da parte dei nuovi collaboratori. Il mio obiettivo a lungo termine è costruire la community della documentazione, in modo che l'apprendimento dalla documentazione sia un'esperienza di dare e ricevere, educare e comunicare. Questo modello di documentazione fonda la formazione e l'esperienza effettiva per i nuovi arrivati e i potenziali collaboratori.
Ragionamento
Questa proposta di Google Summer of Docs è importante per i miei obiettivi pedagogici e professionali. Uso NumPy e SciPy in tutti i miei corsi. I miei studenti hanno difficoltà a consultare la documentazione attuale. Voglio usare la mia esperienza nell'insegnamento ai master non informatica della programmazione per aiutare a organizzare, modificare e colmare le lacune nei tutorial attuali. In seguito, posso utilizzare la documentazione come libro di testo e materiale di riferimento per i miei corsi. Ho creato decine di tutorial, esercizi ed esempi utilizzando Python e
Obiettivi specifici
Ho tre obiettivi specifici per questa proposta Summer of Docs di Google: 1. Organizzare la documentazione attuale, 2. Modificare i tutorial attuali (Guida per principianti, Creazione di array, Indicizzazione, Algebra lineare e NumPy per Matlab) per spostare le informazioni di riferimento nello Spazio spiegazioni e 3. Creare materiali didattici con gli studenti. Ogni obiettivo specifico ha un risultato atteso 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. Questi obiettivi contribuiscono inoltre a promuovere a lungo termine l'obiettivo di continuare a far crescere la community di documentazione di NumPy. Risultati previsti
Ho tre risultati attesi, come questi: 1. Una pagina web di documentazione rivista che separa chiaramente i quattro spazi: tutorial, istruzioni, spiegazione e riferimento, 2. nuovi tutorial per: lettura e scrittura di array, creazione di array (np.zeros, np.ones, np.block, ecc.) e operazioni di algebra tra elementi e lineari in NumPy e 3. uno spazio di istruzioni selezionato.
Questi risultati attesi aiuteranno i nuovi utenti ad avanzare nei documenti, a fornire ai potenziali collaboratori alla documentazione con stili e formati chiari, a rendere i tutorial attuali più brevi e più facili da seguire, a spostare le spiegazioni in una sezione separata e i nuovi collaboratori alla documentazione potranno contribuire alla sezione di istruzioni con piccoli casi d'uso senza creare l'intera documentazione di Sphinx. Vogliamo continuare a costruire la nostra community di insegnamento e apprendimento.
I collaboratori della nuova documentazione possono offrire piccoli casi d'uso a milioni di utenti senza creare l'intera documentazione di Sphinx. Vogliamo continuare a costruire la nostra community di insegnamento e apprendimento. La documentazione proposta imita l'attuale documentazione open source, come Matplotlib, Divio e così via. I nuovi utenti e i potenziali collaboratori avranno più tempo per imparare ad applicare NumPy nei loro campi e software.
La tempistica del progetto va dal 14/09 al 30/11. Il primo passaggio consiste nel creare la documentazione e separare i contenuti dei tutorial correnti in contenuti tutorial, tutorial e spiegazione. Ciò verrà fatto nelle prime cinque settimane del progetto nell'ambito dei risultati 1 e 2, rispettivamente, della revisione del sito web e dei tutorial. L'organizzazione della documentazione proposta è mostrata nella documentazione proposta di seguito.
Documentazione proposta:
i.Tutorials:
- Nozioni di base assoluti per principianti (rimuovi l'installazione, l'importazione/esportazione dei panda può essere sostituita con numpy.loadtxt?)
- link a "Che cos'è numpy"
- link alle istruzioni di installazione di base qui
- Tutorial della guida rapida (per il follow-up del tutorial Python)
- Utilizzo degli array NumPy
- creazione di array (np.zeros, np.ones, np.block, ecc.) (scrivi: priorità media-bassa)
- operazioni a livello di elemento (+,-,*,/) e operazioni di algebra lineare (+,-,@, linalg.solve) (priorità write:med)
- Lettura e scrittura di dati utilizzando Numpy (scrittura: alta priorità)
- Indicizzazione
ii. Istruzioni:
- Algebra lineare su matrici 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 didattici numpy-tutorials (lavoro continuo)
iii. Spiegazione:
- Tipi di dati
- I/O con Numpy
- Indicizzazione
- Trasmissione in corso…
- Cambio byte
- Array strutturati
- Scrittura di container di array personalizzati
- ndarray di sottoclassi
- Varie
iv. Spazio di riferimento:
- Glossario
- Riferimento API Numpy
- Numpy per gli utenti Matlab (la tabella di equivalente è un'ottima tabella di riferimento, ma la discussione su array/matrice è fonte di distrazione e sembra deprecata)
Dopo aver completato questa stagione di Documenti Google, propongo i seguenti risultati:
- Una pagina web di documentazione rivista che separa chiaramente i quattro spazi: Tutorial, Istruzioni, Spiegazione e Riferimenti
- Nuovi tutorial per: creazione di array (np.zeros, np.ones, np.block, ecc.), operazioni a livello di elemento (+,-,*,/) e operazioni di algebra lineare (+,-,@, linalg.solve) e lettura e scrittura di dati utilizzando Numpy (priorità alta)
- Ha raccomandato documenti didattici per aumentare i contributi degli utenti e contribuire a promuovere gli obiettivi della comunità nell'insegnamento e nell'apprendimento
Ciascun risultato prevede una serie di passaggi descritti di seguito nelle tabelle dei risultati 1-3. Mentre la documentazione proposta viene inviata per la revisione, il tutorial "Lettura/scrittura array" ad alta priorità verrà scritto per l'invio come richiesta di pull nell'ambito del Risultato 2. Durante la revisione del sito web rivisto e del tutorial "Read/Write array" aggiornato, inizierò a scrivere un tutorial per la creazione di array utilizzando le funzioni di NumPy, ad esempio np.ones, np.zeros, np.diag. Il tempo rimanente verrà utilizzato per rispondere ai problemi di richiesta di pull e iniziare a scrivere il tutorial di ranking 3: operazioni di algebra lineare e a livello di elemento in Python.
Il terzo risultato è consigliare agli studenti della University of Connecticut di creare la documentazione nel repository di numpy-tutorials. I tutorial o i documenti didattici inviati saranno blocchi note Jupyter che utilizzano NumPy per risolvere problemi di ingegneria. Utilizzerò alcune delle mie note/esempi del corso per inviare un esempio di blocco note. Consiglierò agli studenti di seguire il layout e la struttura mentre costruiamo un modello e uno schema di inquadratura. Questo risultato offre agli studenti un'esperienza autentica per comunicare concetti e soluzioni a un pubblico più ampio. È una grande opportunità per gli studenti di interagire con la community di NumPy e imparare.
Risultato 1: revisione del sito web Data di consegna Repository di Fork e documentazione della build con Sphinx 21/09 Crea una pagina web con quattro spazi definiti e collegati il 1° ottobre Spostare i tutorial attuali negli spazi appropriati e creare i documenti 10/10 Inviare PR a github con le modifiche proposte l'1/11 Rispondere ai commenti/suggerimenti e rivedere il PR3/Sito web rivisto con Risultato 1
Risultato 2: revisione dei tutorial Data di consegna Revisione del ranking delle revisioni dei tutorial 9/21 Separa i contenuti del tutorial corrente in spazi di tutorial e spiegazioni 10/1 Scrittura di ranking 1: lettura/scrittura di array 10/10 Invio di PR a github per separazione e revisione 10/20 Scrivere il ranking 2: creazione di array PR 11/15 e classificazione 1 di elemento lineare 0
Ranking proposto delle revisioni dei tutorial (soggetto a modifiche in base ai mentori/alla community):
Pagina attualmente vuota per gli array di lettura/scrittura
Creazione di array (np.zeros, np.ones, np.block ecc.) Non esiste: aiuterebbe i nuovi utenti a spiegare e dimostrare gli strumenti comuni di creazione/interazione di array
Operazioni di algebra lineare e basata sugli elementi (+,-,*,/ e +,-@,linalg.solve) Non esiste: questa opzione è particolarmente utile per la versione 1. Utenti Matlab e 2. Persone che adottano per l'algebra lineare (machine learning, regressione lineare ecc.)
Risultato 3: spazio di istruzioni curato Data di consegna Link esterno(problema/esempio)
Esempio di creazione di istruzioni (candidato: Come trovare frequenze naturali delle corde per chitarra 10/20
Crea un modello di istruzioni per i nuovi collaboratori l'1/10 in corso Modello tutorial PR e framing possibili contributi
Collaborare con altri collaboratori per creare blocchi note di istruzioni1 e reclutare altri membri della comunità e ottenere lo stato di lavoro approvato da UConn7)
Significato previsto
Questa proposta di Google Summer of Docs sarà utile per creare la documentazione di NumPy, compilare i tutorial mancanti del sito web e ottenere collaboratori per la documentazione. In qualità di professore in ingegneria meccanica, ho intenzione di segmentare la documentazione in modo che i miei studenti siano in grado di esplorare i documenti e di trovare facilmente tutorial introduttivi o guide pratiche. La documentazione segmentata (tutorial, istruzioni, riferimenti e spiegazioni) fornirà esempi strutturati ai potenziali collaboratori per la creazione di nuove risorse. La documentazione proposta si presta a un approccio di dare e avere attraverso un'esperienza formativa e comunicativa per utenti nuovi ed esperti. La consulenza sui documenti illustrativi proposta con gli studenti dell'Università del Connecticut metterà in pratica questa idea educare e comunicare. Vogliamo che tutti gli utenti trovino spazio per sperimentare, imparare e unirsi alla community di NumPy.
Riferimenti
- Sito web NumPy.org visitato il 7/2020.
- GitHub di NumPy.
- Il Sistema di documentazione. Divio.com ultimo accesso il 07/2020.
- Dewey, John. Democrazia e istruzione. Progetto Gutenberg, agosto 2015.
- Dewey, John. Alla ricerca di Certainty George Allen e Unwin Limited. 06/2005.