Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- NumPy
- Rédacteur technique:
- cooperrc
- Nom du projet:
- Documentation NumPy pour l'enseignement communautaire
- Durée du projet:
- Durée standard (3 mois)
Project description
Introduction
NumPy fournit des calculs propres et rapides basés sur des tableaux, dans une bibliothèque logicielle Open Source sans frais. Il s'agit d'un pack fondamental de la pile SciPy pour l'informatique scientifique [1]. Plus de 370 000 projets utilisent le calcul en tableau efficace [2]. Les utilisateurs de NumPy sont accueillis par un nouveau site Web qui propose des applications et des études de cas [1]. Lorsqu'un nouvel utilisateur arrive sur la page de documentation, il accède à de nombreux liens "Commencez ici" et à des tutoriels d'introduction qui peuvent être insurmontables pour un débutant, comme les principes de base de NumPy/la conversion d'octets. J'ai commencé à utiliser NumPy il y a dix ans, à l'école supérieure. Je me suis retrouvée à assembler des articles de blog, des notes de cours et des réponses sur StackExchange pour éviter de parcourir la documentation NumPy. Il existe actuellement plus de 360 000 conversations Stack Exchange concernant NumPy. J'imagine que d'autres utilisateurs ont eu des parcours similaires pour réussir avec NumPy. La communication et la communauté [4] sont à la base des outils éducatifs. La documentation doit établir une communauté qui reflète les objectifs souhaités du projet. La documentation doit être claire et cohérente pour un nouvel utilisateur. Les tutoriels doivent offrir aux nouveaux utilisateurs des étapes faciles à suivre et leur permettre de 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 lieu propice à l'exploration et à la communication. Cette proposition permettra d'organiser et de combler les lacunes de la documentation actuelle de NumPy afin d'informer les nouveaux utilisateurs et de les accueillir dans la communauté.
Les connaissances que les utilisateurs communiquent sont acquises par les tests et l'expérimentation [4,5]. Les connaissances dépendent de la méthode de test et d'évaluation. Le contenu qui fournit des objectifs et des applications clairs dans les tutoriels permet 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 pratique offre un double avantage. Tout d'abord, les utilisateurs nouveaux et expérimentés ont un ensemble d'objectifs clairs à tester et à élaborer. Deuxièmement, les contributeurs potentiels à la documentation ont un espace pour communiquer leurs objectifs, méthodes et solutions. L’espace dédié à la formation répond à un besoin immédiat de rendre la documentation de NumPy plus accessible aux nouveaux utilisateurs et aux contributeurs potentiels. Connaissances actuelles
Selon John Dewey, l'apprentissage repose sur une expérience authentique [4]. La communauté NumPy offre une expérience extraordinaire à 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.
La documentation logicielle contient quatre grands groupes [3]: l'espace tutoriel, l'espace pratique, l'espace d'explication et l'espace de référence. La documentation NumPy contient un certain nombre de documents dans l'espace du tutoriel qui incluent des explications et du contenu d'espacement dans le tutoriel. L’espace de tutoriel doit se concentrer sur la formation des utilisateurs et utiliser des étapes faciles à répéter pour communiquer des idées. L’espace pratique fournit des procédures plus orientées vers les objectifs que les utilisateurs peuvent appliquer dans des applications réelles. L'espace d'explication fournit des informations détaillées sur les doc-strings de chaque fonction. Le tutoriel actuel et les espaces pour les tutoriels 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". Il existe également une excellente référence pour les utilisateurs de Matlab afin de créer du code Numpy dans "Numpy pour les utilisateurs de Matlab". La documentation est plus claire en délimitant ces quatre espaces.
Insuffisance dans la base de connaissances/Besoin non satisfait
La documentation actuelle couvre de nombreux sujets nécessaires, mais ne fait pas clairement la distinction entre les espaces pour les tutoriels, les tutoriels, les explications et les références. Cela peut prêter à confusion pour les contributeurs potentiels. Les nouveaux utilisateurs peuvent se sentir submergés par les explications et les références incluses dans la section du tutoriel, et les contributeurs potentiels rencontrent des difficultés pour apporter leur contribution. Je propose une mise en page plus accessible aux nouveaux arrivants et aux éventuels contributeurs de documentation, avec un flux logique dans la documentation et la gestion des demandes d'extraction pour les documents pratiques fournis par les utilisateurs par les nouveaux contributeurs. Mon objectif à long terme est de développer la communauté de la documentation afin que l'apprentissage de la documentation soit une expérience d'échange et de communication. Ce modèle de documentation appuiera la formation sur l'expérience réelle des nouveaux arrivants et des contributeurs potentiels.
Justification
Cette proposition Google Summer of Docs est importante pour mes objectifs pédagogiques et professionnels. J'utilise NumPy et SciPy dans tous mes cours. La documentation actuelle est difficile à parcourir pour mes élèves. Je souhaite mettre à profit mon expérience de l’enseignement de matières non-informatiques sur le codage pour aider à organiser, modifier et combler les lacunes dans les tutoriels actuels. Ensuite, je peux utiliser la documentation comme manuel et support de référence pour mes cours. J'ai créé des dizaines de tutoriels, d'exercices et d'exemples en utilisant Python et
Objectifs spécifiques
Cette proposition Google Summer of Docs s'articule autour de trois objectifs: 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éer des supports de cours 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. Les objectifs à long terme contribuent également au développement de la communauté de documentation de NumPy. Résultats attendus
J'obtiens trois résultats attendus en tant que tels: 1. Une page Web de documentation révisée qui sépare clairement les quatre espaces: tutoriels, tutoriels, explications et références, 2. nouveaux tutoriels pour: lecture et écriture de tableaux, création de tableaux (np.zeros, np.ones, np.block, etc.) et opérations d'algèbre par élément par rapport à l'algèbre linéaire dans NumPy, et 3. un espace de démonstration personnalisé.
Ces résultats attendus aideront les nouveaux utilisateurs à progresser dans les documents, fourniront des styles et des formats clairs aux contributeurs potentiels à la documentation, rendre les tutoriels actuels plus courts et plus faciles à suivre, déplacer les explications dans une section distincte, et les nouveaux contributeurs à la documentation pourront contribuer à de petits cas d'utilisation à la section Tutoriel sans avoir à créer toute une documentation Sphinx. Nous voulons continuer à développer notre communauté d'enseignants et d'apprenants.
De nouveaux contributeurs à la documentation peuvent contribuer à de petits cas d'utilisation pour des millions d'utilisateurs sans avoir à élaborer toute la documentation Sphinx. Nous voulons continuer à développer notre communauté d'enseignants et d'apprenants. Cette documentation proposée imitera la documentation Open Source actuelle, comme Matplotlib, Divio, etc. Les nouveaux utilisateurs et les contributeurs potentiels pourront apprendre plus facilement à appliquer NumPy dans leurs domaines et logiciels.
La date limite pour le projet est du 14/09 au 30/11. La première étape consiste à créer la documentation et à séparer le contenu des tutoriels actuels sous forme de tutoriel, de tutoriel et d'explication. Cela se fera au cours des cinq premières semaines du projet, dans le cadre des résultats 1 et 2, révision du site Web et des tutoriels, respectivement. L'organisation de la Documentation proposée est présentée dans la Documentation proposée ci-dessous.
Documentation proposée:
i.Tutorials:
- Principes de base absolus pour les débutants (supprimer l'installation, peut-on remplacer l'importation/exportation de Pandas par numpy.loadtxt ?)
- vers "Qu'est-ce que Numpy ?"
- lien vers les instructions d'installation de base
- Tutoriel de démarrage rapide (destiné à suivre le tutoriel Python)
- Utiliser des tableaux NumPy
- Création de tableaux (np.zeros, np.ones, np.block, etc.) (priorité moyenne à faible)
- Opérations par élément (+,-,*,/) et opérations d'algèbre linéaire (+,-,@, linalg.solve) (priorité write:med)
- 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 dimensions (on aimerait modifier les en-têtes et les descriptions, et peut-être remplacer le titre par "Traitement des images avec l'algèbre linéaire de Numpy")
- lien vers le contenu de tutoriel numpy-tutorials (travail en cours)
iii. Explication :
- Types de données
- E/S avec Numpy
- Indexation
- Diffusion…
- Échange d'octets
- Tableaux structurés
- Écrire des conteneurs de tableaux personnalisés
- sous-classement de ndarray
- Divers
iv. Espace de référence:
- Glossaire
- Documentation de référence sur l'API Numpy
- Numpy pour les utilisateurs de Matlab (le tableau d'équivalence est une excellente table de référence, mais la discussion sur les tableaux/la matrice est gênante et semble obsolète)
À la fin de cette saison de Google Docs, je propose les résultats suivants:
- Une page Web de documentation révisée qui sépare clairement les quatre espaces: Tutoriels, Tutoriel, explication et Référence
- Nouveaux tutoriels pour la création de tableaux (np.zeros, np.ones, np.block, etc.), les opérations par élément (+,-,*,/) et les opérations d'algèbre linéaire (+,-,@, linalg.solve), et la lecture et l'écriture de données à l'aide de Numpy (priorité élevée)
- Fourniture de documents pratiques pour augmenter les contributions des utilisateurs et aider la communauté à atteindre les objectifs d'enseignement et d'apprentissage
Chaque résultat comporte un certain nombre d'étapes décrites ci-dessous dans les tableaux relatifs aux résultats 1 à 3. Bien que la documentation proposée soit soumise pour examen, le tutoriel de haute priorité « Lecture/écriture de tableaux » sera écrit pour être soumis en tant que demande d'extraction dans le cadre du Résultat 2. Lors de l'examen du site Web révisé et de la mise à jour du tutoriel "Lire/Écrire des tableaux", je commencerai à écrire un tutoriel pour créer des tableaux à l'aide de fonctions NumPy telles que np.ones, np.zeros, 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 les documents pratiques envoyés seront des notebooks Jupyter qui utilisent NumPy pour résoudre des problèmes d'ingénierie. Je vais utiliser certaines de mes notes/exemples de cours pour soumettre un exemple de bloc-notes. Je conseillerai aux participants de suivre la mise en page et la structure à mesure que nous créerons un modèle et un plan de cadrage. Ce résultat leur permet de communiquer des concepts et des solutions à un public plus large. C'est une excellente occasion pour les étudiants de s'impliquer dans la communauté NumPy et d'apprendre.
Résultat 1: Réviser le site Web "Livrable Date Repository" et Créer des documents avec Sphinx le 21/09 Créer une page Web avec quatre espaces définis et liés le 01/10 Déplacer les tutoriels actuels dans les espaces appropriés et créer des documents le 10/10 Envoyer une demande d'informations à GitHub avec les modifications proposées le 11/1 Répondre aux commentaires/suggestions et modifier le PR en cours avec Résultat 12 Site Web révisé
Résultat 2 : Réviser les tutoriels Date de livraison Voir le classement des révisions des tutoriels 21/09 Séparer le contenu du tutoriel actuel dans les espaces de tutoriel et d'explication 10/1 Écrire le rang 1 : lire/écrire les tableaux 10/10 Envoyer le PR à GitHub pour la séparation et la révision 10/20 Écrire le classement 2 : création de tableau PR 11/15 : rang 2 linéaire - rang 0/15 : écriture linéaire
Classement proposé pour les révisions du tutoriel (sujet à modification selon les mentors/la communauté):
Page de lecture/écriture des tableaux actuellement vides
Création de tableaux (np.zeros, np.ones, np.block, etc.) N'existe pas: aiderait les nouveaux utilisateurs à expliquer et démontrer les outils courants de création/d'interaction de tableaux
Les opérations d'algèbre linéaire par élément (+,-,*,/ et +,-@,linalg.solve) n'existent pas: ceci est particulièrement utile pour 1. Des utilisateurs de Matlab et 2. Personnes adoptant l'algèbre linéaire (machine learning, régression linéaire, etc.)
Résultat 3: Espace de formation sélectionné Date de livrable Lien externe(problème/exemple)
Créer un exemple de guide (candidat: trouver des fréquences naturelles de cordes de guitare 20/10
Créer un modèle de guide pour les nouveaux contributeurs 01/10 en cours Modèle de contributions Relations publiques et cadrage possibles
Collaborer avec d'autres contributeurs pour créer des notebooks pratiques/d'autres membres de la communauté qui arrivent sur le projet :
Signification attendue
Cette proposition Google Summer of Docs permettra d'enrichir la documentation NumPy , de compléter les tutoriels manquants sur le site Web et d'attirer des contributeurs à la documentation. En tant que professeur de génie mécanique, je prévois de segmenter la documentation de manière à ce que mes élèves puissent parcourir les documents et trouver facilement des tutoriels d'introduction plutôt que des guides pratiques. La documentation segmentée (le tutoriel, le guide d'utilisation, la documentation de référence et l'explication) donnera 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 et de communication pour les utilisateurs nouveaux et expérimentés. Le projet de document pratique proposé aux étudiants de l'Université du Connecticut mettra en pratique cette idée d'enseignement et de communication. Nous souhaitons que tous les utilisateurs trouvent de la place pour expérimenter, apprendre et rejoindre la communauté NumPy.
Références
- Site Web NumPy.org consulté le 07/2020.
- Dépôt GitHub NumPy.
- Le système de documentation. Divio.com a été consulté le 07/2020.
- Dewey et John. Démocratie et éducation. Projet Gutenberg, août 2015.
- Dewey et John. Quête de Certainty George Allen And Unwin Limited. 06/2005.