Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- NumPy
- Rédacteur technique:
- cooperrc
- Nom du projet:
- Documentation NumPy pour l'éducation de la communauté
- Durée du projet:
- Durée standard (3 mois)
Project description
Introduction
NumPy fournit un calcul basé sur des tableaux clair et rapide dans une bibliothèque logicielle Open Source sans frais. Il s'agit d'un package fondamental de la pile SciPy pour le calcul scientifique [1]. Plus de 370 000 projets l'utilisent pour un calcul matriciel efficace [2]. Les utilisateurs de NumPy sont accueillis par un nouveau site Web proposant des applications et des études de cas [1]. Lorsqu'un nouvel utilisateur accède à la page de documentation, il reçoit de nombreux liens "Start Here" et des tutoriels d'introduction qui peuvent être déroutants pour un débutant, comme NumPy Basics ou le échange d'octets. J'ai commencé à utiliser NumPy il y a dix ans à l'école supérieure. Je me suis retrouvée à rassembler des articles de blog, des notes de cours et des réponses sur Stack Exchange pour éviter de parcourir la documentation NumPy. Il existe actuellement plus de 360 000 conversations Stack Exchange liées à NumPy. J'imagine que d'autres utilisateurs ont eu des chemins similaires vers le succès sur NumPy. Les outils pédagogiques reposent sur la communication et la communauté [4]. La documentation doit établir une communauté qui reflète les objectifs souhaités du projet. La documentation doit être cohérente et claire pour un nouvel utilisateur. Les tutoriels doivent fournir aux nouveaux utilisateurs des étapes faciles à suivre et les aider à se familiariser avec la bibliothèque [3]. La documentation doit accueillir un nouvel utilisateur dans la communauté NumPy. La structure, le rythme et les auteurs de la documentation doivent tous créer un espace propice à l'exploration et à la communication. Cette proposition vise à organiser et à combler les lacunes de la documentation NumPy actuelle afin que les nouveaux utilisateurs soient informés et accueillis dans la communauté.
Les connaissances que les utilisateurs communiquent sont acquises par le biais de tests et d'expérimentations [4,5]. Les connaissances dépendent de la méthode de test et d'évaluation. Les contenus qui fournissent des objectifs et des applications clairs dans les tutoriels permettent aux utilisateurs de tester et d'évaluer de nouvelles idées et méthodes. La communauté peut créer une base de connaissances pour améliorer les compétences, les faits et les applications. L'espace "Comment faire" présente un double avantage. Tout d'abord, les utilisateurs nouveaux et expérimentés ont un ensemble d'objectifs clairs à tester et à créer. Deuxièmement, les contributeurs potentiels à la documentation ont un espace pour communiquer leurs objectifs, leurs méthodes et leurs solutions. L'espace de démonstration répond à un besoin immédiat de rendre la documentation de NumPy plus accessible aux nouveaux utilisateurs et aux contributeurs potentiels. Connaissances actuelles
John Dewey a déclaré que l'apprentissage repose sur une expérience authentique [4]. La communauté NumPy dispose d'une expérience réelle considérable qu'elle peut partager avec d'autres utilisateurs. L'éducation repose sur la communauté et la communication. Une page de documentation organisée permet aux nouveaux utilisateurs de découvrir NumPy. Il crée également un modèle structuré permettant aux contributeurs potentiels de communiquer leurs expériences dans NumPy.
Il existe quatre espaces largement regroupés pour la documentation logicielle [3]: l'espace des tutoriels, l'espace des tutoriels, l'espace d'explication et l'espace de référence. La documentation NumPy contient un certain nombre de documents dans l'espace de tutoriel qui mélangent des explications et des instructions. L'espace de tutoriel doit se concentrer sur l'éducation des utilisateurs et utiliser des étapes faciles à répéter pour communiquer des idées. Le guide pratique propose des procédures davantage axées sur les objectifs que les utilisateurs peuvent appliquer dans des applications réelles. L'espace d'explication fournit des informations détaillées sur les chaînes de documentation de chaque fonction. Les espaces de tutoriel et d'instructions actuels ne sont pas clairement délimités et entrent parfois dans l'espace d'explication et de référence. Il existe un excellent tutoriel pour le niveau "Débutant absolu". Les utilisateurs de Matlab disposent d'une excellente référence pour créer du code Numpy dans "Numpy pour les utilisateurs de Matlab". La délimitant clairement ces quatre espaces permet de clarifier la documentation.
Lacune de la base de connaissances/Besoins non satisfaits
La documentation actuelle couvre de nombreux sujets nécessaires, mais ne fait pas la distinction claire entre les tutoriels, les guides, les explications et les espaces de référence. Cela peut prêter à confusion pour les contributeurs potentiels. Les nouveaux utilisateurs peuvent être submergés par les explications et les documents de référence de la section de tutoriel, et les contributeurs potentiels doivent surmonter des obstacles pour contribuer. Je propose une mise en page plus accessible pour les nouveaux utilisateurs et les contributeurs potentiels à la documentation, avec un flux logique dans la documentation et la gestion des requêtes pull pour les documents d'instructions créés par les nouveaux contributeurs. Mon objectif à long terme est de créer une communauté de documentation afin que l'apprentissage à partir de la documentation soit une expérience d'enseignement et de communication basée sur un échange. Ce modèle de documentation fondera l'éducation sur l'expérience réelle des nouveaux arrivants et des contributeurs potentiels.
Justification
Cette proposition de Google Summer of Docs est importante pour mes objectifs pédagogiques et professionnels. Je les utilise dans tous mes cours. La documentation actuelle est difficile à parcourir pour mes élèves. Je souhaite utiliser mon expérience en enseignement à des étudiants non spécialisés en informatique à coder pour aider à organiser, modifier et combler les lacunes des tutoriels actuels. Je peux ensuite utiliser la documentation comme manuel et comme document de référence pour mes cours. J'ai créé des dizaines de tutoriels, d'exercices et d'exemples à l'aide de Python et de
Objectifs spécifiques
Cette proposition de Google Summer of Docs a trois objectifs spécifiques: 1. Organiser la documentation actuelle, 2. Modifier les tutoriels actuels (Guide du débutant, Création de tableaux, Indexation, Algèbre linéaire et NumPy pour Matlab) afin de déplacer les informations de référence dans l'espace d'explication 3. Créez des tutoriels avec les élèves. Chaque objectif spécifique a un résultat attendu pour la proposition.
Ces trois objectifs spécifiques visent à rendre la documentation plus accueillante pour les nouveaux utilisateurs et à fournir une structure aux contributeurs potentiels. Ces objectifs contribuent également à poursuivre l'objectif à long terme de développer la communauté de documentation NumPy. Résultats attendus
J'attends les trois résultats suivants: 1. Une page Web de documentation révisée qui sépare clairement les quatre espaces: tutoriels, instructions, explication et référence, 2. nouveaux tutoriels pour: lecture et écriture de tableaux, création de tableaux (np.zeros, np.ones, np.block, etc.) et opération d'algèbre linéaire par élément dans NumPy, et 3. un espace de guide organisé.
Ces résultats attendus aideront les nouveaux utilisateurs à progresser dans les documents, fourniront aux contributeurs potentiels des styles et des formats clairs, rendront les tutoriels actuels plus courts et plus faciles à suivre, déplaceront les explications dans une section distincte, et les nouveaux contributeurs pourront contribuer à de petits cas d'utilisation dans la section "Comment faire" sans créer une documentation Sphinx complète. Nous souhaitons continuer à développer notre communauté d'enseignement et d'apprentissage.
Les nouveaux contributeurs de documentation peuvent contribuer à de petits cas d'utilisation pour des millions d'utilisateurs sans avoir à compiler toute la documentation Sphinx. Nous souhaitons continuer à développer notre communauté d'enseignement et d'apprentissage. Cette documentation proposée imitera la documentation Open Source actuelle, comme Matplotlib, Divio, etc. Les nouveaux utilisateurs et les contributeurs potentiels pourront plus facilement apprendre à appliquer NumPy dans leurs domaines et leurs logiciels.
La période du projet s'étend du 14 septembre au 30 novembre. La première étape consiste à créer la documentation et à séparer le contenu des tutoriels actuels en tutoriels, guides et explications. Cela se fera au cours des cinq premières semaines du projet, dans le cadre des résultats 1 et 2, qui consistent à réviser le site Web et les tutoriels, respectivement. La structure de la documentation proposée est présentée ci-dessous.
Documentation proposée:
i.Tutorials:
- Principes de base absolus pour les débutants (suppression de l'installation, l'importation/exportation pandas peut-elle être remplacée par numpy.loadtxt ?)
- lien vers "What is numpy"
- lien vers les instructions d'installation de base
- Tutoriel de démarrage rapide (à suivre après le tutoriel Python)
- Utiliser des tableaux NumPy
- Création de tableaux (np.zeros, np.ones, np.block, etc.) (écriture: priorité moyenne faible)
- opérations par élément (+,-,*,/) et opérations d'algèbre linéaire (+,-,@, linalg.solve) (priorité écriture:moyenne)
- Lire et écrire des données à l'aide de Numpy (écriture: priorité élevée)
- Indexation
ii. Tutoriels:
- Algèbre linéaire sur des tableaux n-dimensionnels (j'aimerais modifier les titres et les descriptions, et peut-être changer le titre en "Traitement d'image avec l'algèbre linéaire de Numpy")
- lien vers le contenu de tutoriels numpy (travail en cours)
iii. Explication :
- Types de données
- E/S avec Numpy
- Indexation
- Diffusion
- Permutation d'octets
- Tableaux structurés
- Écrire des conteneurs de tableaux personnalisés
- sous-classer ndarray
- Divers
iv. Espace de référence:
- Glossaire
- Documentation de référence de l'API Numpy
- Numpy pour les utilisateurs de Matlab (la table d'équivalence est une excellente table de référence, mais les discussions sur les tableaux et les matrices sont gênantes et semblent obsolètes)
À la fin de cette saison Google dédiée aux documents, je vous propose les résultats suivants:
- Page Web de documentation révisée qui sépare clairement les quatre espaces: tutoriels, guides, explications et références
- Nouveaux tutoriels sur la création de tableaux (np.zeros, np.ones, np.block, etc.), les opérations élémentaires (+,-,*,/) et les opérations d'algèbre linéaire (+,-,@, linalg.solve), ainsi que sur la lecture et l'écriture de données à l'aide de Numpy (priorité élevée)
- Conseils sur les documents de procédure pour encourager les contributions des utilisateurs et les aider à atteindre les objectifs de la communauté en matière d'enseignement et d'apprentissage
Chaque résultat comporte un certain nombre d'étapes décrites ci-dessous dans les tableaux des résultats 1 à 3. Pendant que la documentation proposée est envoyée pour examen, le tutoriel de priorité élevée "Lire/écrire des tableaux" sera rédigé pour être envoyé en tant que requête pull dans le cadre du résultat 2. Pendant l'examen du site Web révisé et du tutoriel mis à jour sur la lecture/l'écriture de tableaux, je vais commencer à rédiger un tutoriel sur la création de tableaux à l'aide de fonctions NumPy, par exemple np.ones, np.zeros et np.diag. Le temps restant sera utilisé pour répondre aux problèmes de demande d'extraction et commencer à écrire le tutoriel de rang 3: Opérations d'algèbre linéaire et par élément en Python.
Le troisième résultat consiste à conseiller aux étudiants de l'université du Connecticut de créer de la documentation dans le dépôt numpy-tutorials. Les tutoriels ou documents pratiques envoyés sont des notebooks Jupyter qui utilisent NumPy pour résoudre les problèmes d'ingénierie. Je vais utiliser certains de mes notes/exemples de cours pour envoyer un exemple de notebook. Je conseillerai aux élèves de suivre la mise en page et la structure lorsque nous créerons un modèle et un schéma de cadrage. Ce résultat offre aux élèves une véritable expérience de communication de concepts et de solutions à un public plus large. C'est une excellente occasion pour les élèves de s'impliquer dans la communauté NumPy et d'apprendre.
Résultat 1: Réviser le site Web Date de livraison Fork Repository et Build Docs avec Sphinx 9/21 Créer une page Web avec quatre espaces définis et liés 10/1 Déplacer les tutoriels actuels dans les espaces appropriés et créer des documents 10/10 Envoyer une demande de publication sur GitHub avec les modifications proposées 11/1 Répondre aux commentaires/suggestions et réviser la demande de publication en cours avec le résultat 2 Site Web révisé 11/30
Résultat 2: Réviser les tutoriels Date de livraison Examiner le classement des révisions des tutoriels 9/21 Séparer le contenu actuel du tutoriel en espaces "Tutoriel" et "Explication" 10/1 Écrire le rang 1: PR de lecture/écriture des tableaux 10/10 Envoyer une PR à GitHub pour la séparation et la révision 10/20 Écrire le rang 2: PR de création de tableaux 11/15 Écrire le rang 3: PR d'opérations élément par élément et d'algèbre linéaire 11/30
Classement proposé des révisions du tutoriel (susceptible d'être modifié en fonction des mentors/de la communauté):
Page actuellement vide des tableaux de lecture/écriture
Création de tableaux (np.zeros, np.ones, np.block, etc.) Il n'existe pas: il serait utile que les nouveaux utilisateurs puissent voir et comprendre les outils courants de création et d'interaction avec les tableaux
Les opérations élément par élément et d'algèbre linéaire (+,-,*,/ et +,-@,linalg.solve) n'existent pas. Cela est particulièrement utile pour 1. Utilisateurs Matlab et 2. Les personnes qui adoptent l'algèbre linéaire (machine learning, régression linéaire, etc.)
Résultat 3: Espace de tutoriels sélectionnés Date de livraison Lien externe(problème/exemple)
Créer un exemple de tutoriel (candidat: trouver les fréquences naturelles des cordes de guitare 10/20
Créer un modèle de tutoriel pour les nouveaux contributeurs 10/1 en cours Préparation du tutoriel et présentation des contributions possibles
Collaborer avec d'autres contributeurs pour créer des cahiers de tutoriels recrutant des étudiants de l'université UConn et d'autres membres de la communauté 7/1: stage approuvé et demandes en cours
Signification attendue
Cette proposition de Google Summer of Docs permettra de rendre la documentation NumPy plus accessible, de compléter les tutoriels manquants sur le site Web et d'attirer de nouveaux contributeurs à la documentation. En tant que professeur en génie mécanique, je prévois de segmenter la documentation de manière à ce que mes étudiants puissent naviguer dans les documents et trouver facilement des tutoriels d'introduction et des guides pratiques. La documentation segmentée (tutoriel, guide, référence et explication) fournira aux contributeurs potentiels des exemples structurés pour créer de nouvelles ressources. La documentation proposée se prête à une expérience de partage par le biais d'une expérience d'éducation et de communication pour les utilisateurs nouveaux et expérimentés. Le document d'aide proposé aux étudiants de l'Université du Connecticut mettra en pratique cette idée d'éducation et de communication. Nous souhaitons que tous les utilisateurs trouvent l'espace nécessaire pour expérimenter, apprendre et rejoindre la communauté NumPy.
Références
- Site Web NumPy.org consulté en juillet 2020.
- Dépôt GitHub NumPy.
- Système de documentation. Consulté sur Divio.com en juillet 2020.
- Dewey, John. Démocratie et éducation Project Gutenberg, août 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.