Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- NumPy
- Technischer Redakteur:
- Coperrc
- Projektname:
- NumPy-Dokumentation für Community Education
- Projektdauer:
- Standardlaufzeit (3 Monate)
Projektbeschreibung
Einführung
NumPy bietet eine kostenlose Open-Source-Softwarebibliothek für saubere und schnelle arraybasierte Berechnungen. Es ist ein grundlegendes Paket im SciPy-Stack für wissenschaftliches Computing [1]. Über 370.000 Projekte nutzen es für effizientes Array-Computing [2]. NumPy-Nutzer werden von einer neuen Website mit Anwendungen und Fallstudien begrüßt [1]. Wenn ein neuer Nutzer auf die Dokumentationsseite stößt, werden ihm mehrere „Start Here“-Links und einführende Anleitungen angezeigt, die für Einsteiger überwältigend sein können, z. B. NumPy-Grundlagen/Byte-Swapping. Ich habe vor zehn Jahren in der Graduiertenschule mit NumPy begonnen. Ich musste Blogbeiträge, Vorlesungsnotizen und StackExchange-Antworten zusammensetzen, um die NumPy-Dokumentation nicht durchgehen zu müssen. Derzeit gibt es über 360.000 StackExchange-Unterhaltungen zu NumPy. Ich kann mir vorstellen, dass andere Nutzer einen ähnlichen Weg zu Erfolg in NumPy hatten. Die Bausteine von Bildungstools sind Kommunikation und Gemeinschaft [4]. Die Dokumentation muss eine Community schaffen, die die gewünschten Ziele des Projekts widerspiegelt. Die Dokumentation sollte eine einheitliche, klare Anleitung für neue Nutzer sein. Die Anleitungen sollten neuen Nutzern leicht verständliche Schritte bieten und sie mit der Bibliothek vertraut machen [3]. Die Dokumentation sollte neue Nutzer in der NumPy-Community willkommen heißen. Die Struktur, das Tempo und die Autoren der Dokumentation müssen einen Ort schaffen, an dem Erkundung und Kommunikation willkommen sind. Mit diesem Vorschlag werden Lücken in der aktuellen NumPy-Dokumentation geschlossen, damit neue Nutzer die Community kennenlernen und sich informieren können.
Das Wissen, das Nutzer kommunizieren, wird durch Tests und Experimente gewonnen [4,5]. Das Wissen hängt von der Test- und Bewertungsmethode ab. Inhalte mit klaren Zielen und Anwendungen in Anleitungen ermöglichen es Nutzern, neue Ideen und Methoden zu testen und zu bewerten. Die Community kann eine Wissensdatenbank aufbauen, um Fähigkeiten, Fakten und Anwendungen zu verbessern. Der Hilfebereich bietet zwei Vorteile. Erstens: Neue und erfahrene Nutzer haben eine Reihe klarer Ziele, die sie testen und mithilfe von Tests erreichen möchten. Zweitens haben potenzielle Mitwirkende an der Dokumentation die Möglichkeit, ihre Ziele, Methoden und Lösungen zu kommunizieren. Der Hilfebereich erfüllt eine unmittelbare Notwendigkeit, die Dokumentation von NumPy für neue Nutzer und potenzielle Mitwirkende zugänglicher zu machen. Aktuelles Wissen
John Dewey sagte, dass die Grundlage des Lernens eine echte Erfahrung ist [4]. Die NumPy-Community hat eine enorme Menge an echten Erfahrungen, die mit anderen Nutzern geteilt werden können. Bildung basiert auf Gemeinschaft und Kommunikation. Eine übersichtlich strukturierte Dokumentationsseite erleichtert es neuen Nutzern, NumPy zu verwenden. Außerdem wird eine strukturierte Vorlage für potenzielle Mitwirkende erstellt, um Erfahrungen mit NumPy zu teilen.
Es gibt vier grob gruppierte Bereiche für Softwaredokumentation [3]: Anleitungsbereich, Anleitungsbereich, Erläuterungsbereich und Referenzbereich. Die NumPy-Dokumentation enthält eine Reihe von Dokumenten im Bereich „Anleitungen“, in denen Erklärungen und Anleitungen kombiniert werden. Der Anleitungsbereich sollte sich auf die Erläuterung der Nutzenden konzentrieren und einfache Schritte beinhalten, um Ideen zu vermitteln. Der Bereich „Anleitungen“ bietet zielorientiertere Verfahren, die Nutzer in der Praxis anwenden können. Der Erläuterungsbereich enthält detaillierte Informationen und Doc-Strings für jede Funktion. Das aktuelle Tutorial und die Anleitungsbereiche sind nicht klar abgegrenzt und werden manchmal in den Erklärungs- und Referenzbereich aufgenommen. Es gibt ein hervorragendes Tutorial für „Absoluter Anfänger“ und eine hervorragende Referenz für Matlab-Nutzer zum Erstellen von NumPy-Code in „Numpy für Matlab-Nutzer“. Die klare Abgrenzung dieser vier Bereiche macht die Dokumentation klarer.
Lücke in der Wissensdatenbank/unerfüllte Anforderung
In der aktuellen Dokumentation werden viele wichtige Themen behandelt, aber es fehlt eine klare Unterscheidung zwischen Anleitung, Anleitung, Erklärung und Referenzbereichen. Das kann für potenzielle Mitwirkende verwirrend sein. Neue Nutzer können sich mit Erklärungen und Referenzmaterial in der Anleitung überfordern und potenzielle Beitragende stehen vor Herausforderungen. Ich schlage vor, dass neue und mögliche Mitwirkende an der Dokumentation ein barrierefreies Layout mit einem logischen Ablauf bei der Dokumentation und der Verwaltung von Pull-Anfragen für von Nutzern bereitgestellte Anleitungsdokumente von neuen Mitwirkenden haben. Mein langfristiges Ziel ist es, die Dokumentations-Community so aufzubauen, dass das Lernen aus der Dokumentation ein Geben und Nehmen, ein Lernen und Kommunizieren ist. Dieses Dokumentationsmodell basiert auf tatsächlichen Erfahrungen von Neulingen und potenziellen Mitwirkenden.
Begründung
Dieser Google Summer of Docs-Vorschlag ist wichtig für meine pädagogischen und beruflichen Ziele. Ich verwende NumPy und SciPy in allen meinen Kursen. Die aktuelle Dokumentation ist für meine Schüler schwierig zu navigieren. Ich möchte meine Erfahrung beim Unterrichten von Nicht-Informatikstudenten beim Programmieren nutzen, um die aktuellen Tutorials zu organisieren, zu bearbeiten und Lücken zu schließen. Dann kann ich die Dokumentation als Lehrbuch und Referenzmaterial für meine Kurse verwenden. Ich habe Dutzende von Anleitungen, Übungen und Beispielen mit Python und
Spezifische Ziele
Ich habe drei konkrete Ziele für diesen Google Summer of Docs-Vorschlag: 1. Organisieren Sie die aktuelle Dokumentation, 2. Bearbeiten Sie die aktuellen Tutorials (Einstiegsleitfaden, Arrayerstellung, Indexierung, Lineare Algebra und NumPy für Matlab), um Referenzinformationen in den Erklärungsbereich zu verschieben. Erstellen Sie mit Schülern oder Studenten Anleitungen. Jedes spezifische Ziel hat ein erwartetes Ergebnis für den Vorschlag.
Diese drei spezifischen Ziele zielen darauf ab, die Dokumentation für neue Nutzer ansprechender zu gestalten und potenziellen Mitwirkenden Struktur zu geben. Die Ziele tragen auch dazu bei, das langfristige Ziel zu erreichen, die NumPy-Dokumentations-Community weiter auszubauen. Erwartete Ergebnisse
Ich habe drei mögliche Ergebnisse: 1. Eine überarbeitete Dokumentationsseite, auf der die vier Bereiche „Anleitungen“, „Anleitungen“, „Erläuterungen“ und „Referenz“ klar voneinander getrennt sind, 2. neue Anleitungen zum Lesen und Schreiben von Arrays, zum Erstellen von Arrays (np.zeros, np.ones, np.block usw.) und zum elementweisen und linearen Algebra-Betrieb in NumPy sowie 3. ein ausgewählter Bereich mit Anleitungen.
Diese erwarteten Ergebnisse werden neuen Nutzern beim Durcharbeiten von Dokumenten helfen, potenziellen Mitwirkenden mit klaren Stilen und Formaten zur Verfügung stellen, aktuelle Anleitungen kürzer und verständlicher gestalten, Erklärungen in einen separaten Abschnitt verschieben, und neue Nutzer, die an der Dokumentation teilnehmen, können kleine Anwendungsfälle zum Anleitungsbereich beisteuern, ohne eine komplette Sphinx-Dokumentation erstellen zu müssen. Wir möchten unsere Community für Lehrende und Lernende weiter ausbauen.
Neue Mitwirkende an der Dokumentation können Millionen von Nutzern kleine Anwendungsfälle zur Verfügung stellen, ohne die gesamte Sphinx-Dokumentation erstellen zu müssen. Wir möchten unsere Lehr- und Lerngemeinschaft weiter ausbauen. Diese vorgeschlagene Dokumentation entspricht aktuellen Open-Source-Dokumentationen wie Matplotlib, Divio usw. Neue Nutzer und potenzielle Beitragende können sich leichter mit der Anwendung von NumPy in ihren Bereichen und ihrer Software vertraut machen.
Der Zeitplan für das Projekt ist der 14. September bis 30. November. Der erste Schritt besteht darin, die Dokumentation zu erstellen und die Inhalte der aktuellen Anleitungen in Anleitungen, Anleitungen und Erklärungen zu unterteilen. Dies geschieht in den ersten fünf Wochen des Projekts im Rahmen der Ergebnisse 1 und 2 – der Überarbeitung der Website bzw. der Anleitungen. Die vorgeschlagene Dokumentationsorganisation ist in der vorgeschlagenen Dokumentation unten dargestellt.
Vorgeschlagene Dokumentation:
i.Tutorials:
- Absolute Grundlagen für Anfänger (Installation entfernen, kann Pandas-Import/-Export durch numpy.loadtxt ersetzt werden?)
- Link zu „Was ist NumPy?“
- Link zur grundlegenden Installationsanleitung
- Kurzanleitung (als Fortsetzung der Python-Anleitung gedacht)
- Mit NumPy-Arrays arbeiten
- Arrayerstellung (np.zeros, np.ones, np.block usw.) (write: med-low priority)
- elementweise Vorgänge (+,-,*,/) und lineare algebraische Vorgänge (+,-,@, linalg.solve) (write:med priority)
- Daten mit Numpy lesen und schreiben (Schreiben: hohe Priorität)
- Indexierung
ii. Anleitungen:
- Lineare Algebra auf n-dimensionalen Arrays (ich würde die Überschriften und Beschreibungen gerne bearbeiten und den Titel vielleicht in „Bildverarbeitung mit der linearen Algebra von Numpy“ ändern)
- Link zu numpy-tutorials-Anleitungen (fortlaufende Arbeit)
iii. Erklärung:
- Datentypen
- E/A mit Numpy
- Indexierung
- Übertragung
- Byte-Swapping
- Strukturierte Arrays
- Benutzerdefinierte Arraycontainer schreiben
- ndarray als Unterklasse
- Sonstige
iv. Referenzbereich:
- Glossar
- Numpy API-Referenz
- Numpy für Matlab-Nutzer (Äquivalenztabelle ist eine gute Referenztabelle, aber die Array-/Matrixdiskussion lenkt ab und scheint veraltet zu sein)
Nach Abschluss dieser Google Season of Docs sollten Sie Folgendes erreicht haben:
- Eine überarbeitete Dokumentationswebseite, auf der die vier Bereiche „Anleitungen“, „Anleitungen“, „Erläuterungen“ und „Referenz“ klar voneinander getrennt sind
- Neue Anleitungen zu: Arrayerstellung (np.zeros, np.ones, np.block usw.), elementweise Operationen (+,-,*,/) und lineare Algebra-Operationen (+,-,@, linalg.solve) sowie Lesen und Schreiben von Daten mit Numpy (hohe Priorität)
- Anleitungen, um die Nutzerbeiträge zu erhöhen und die Ziele der Community in Bezug auf Unterricht und Lernen zu fördern
Für jedes Ergebnis gibt es eine Reihe von Schritten, die unten in den Tabellen für die Ergebnisse 1–3 beschrieben sind. Während die vorgeschlagene Dokumentation zur Überprüfung eingereicht wird, wird das Tutorial mit hoher Priorität „Arrays lesen/schreiben“ als Pull-Request im Rahmen von Ergebnis 2 eingereicht. Während der Überprüfung der überarbeiteten Website und der aktualisierten Anleitung zum Lesen und Schreiben von Arrays werde ich mit dem Schreiben einer Anleitung zum Erstellen von Arrays mit NumPy-Funktionen wie np.ones, np.zeros und np.diag beginnen. Die verbleibende Zeit wird verwendet, um auf Probleme mit Pull-Requests zu reagieren und mit dem Schreiben des Tutorials für den 3. Kursabschnitt zu beginnen: Elementweise und lineare Algebra-Operationen in Python.
Das dritte Ergebnis besteht darin, den Studenten der University of Connecticut zu empfehlen, Dokumentationen im Repository „numpy-tutorials“ zu erstellen. Bei den eingereichten Tutorials oder Anleitungsdokumenten handelt es sich um Jupyter-Notebooks, die NumPy zum Lösen von technischen Problemen verwenden. Ich werde einige meiner Kursnotizen/Beispiele verwenden, um ein Beispielnotizbuch einzureichen. Ich rate den Schülern, beim Erstellen einer Vorlage und eines Framing-Schemas das Layout und die Struktur zu beachten. Dieses Ergebnis bietet den Schülern die Möglichkeit, Konzepte und Lösungen einem breiteren Publikum zu vermitteln. Es ist eine gute Gelegenheit für Studierende, sich mit der NumPy-Community auszutauschen und zu lernen.
Ergebnis 1: Website überarbeiten Abgabetermin Repository forken und Build-Dokumente mit Sphinx erstellen 9/21 Webseite mit vier definierten und verknüpften Bereichen erstellen 10/1 Aktuelle Anleitungen in die entsprechenden Bereiche verschieben und Build-Dokumente erstellen 10/10 PR mit vorgeschlagenen Änderungen an GitHub senden 11/1 Auf Kommentare/Vorschläge reagieren und PR überarbeiten fortgesetzt mit Ergebnis 2 Website überarbeitet 11/30
Ergebnis 2: Tutorials überarbeiten Datum der Liefergegenstände Tutorials Überarbeitungsranking 9/21 Aktuelle Anleitungsinhalte in Tutorial- und Erläuterungsbereiche unterteilen 10/1 Rang 1 schreiben: Arrays lesen/schreiben 10/10 PR zur Trennung und Überarbeitung an GitHub senden
Vorgeschlagene Reihenfolge der Anleitungsüberarbeitungen (je nach Mentoren/Community kann sich diese ändern):
Seite „Lese-/Schreib-Arrays derzeit leer“
Arrays erstellen (z. B. np.zeros, np.ones, np.block) Nicht vorhanden: Hilft neuen Nutzern, die gängigen Tools zum Erstellen/Interaktion von Arrays zu erklären und zu demonstrieren
Elementweise und lineare algebraische Operationen (+,-,*,/ und +,-@,linalg.solve) Nicht vorhanden: Dies ist besonders hilfreich für 1. Matlab-Nutzer und 2. Personen, die die lineare Algebra übernehmen (maschinelles Lernen, lineare Regression usw.)
Ergebnis 3: Kuratierte Anleitungen Abgabetermin externer Link(Problem/Beispiel)
Anleitungsbeispiel erstellen (Kandidat: So finden Sie die natürlichen Frequenzen von Gitarrensaiten 10/20
Anleitungsvorlage für neue Mitwirkende erstellen 10/1 in Arbeit Anleitungsvorlage – PR und Formulierung möglicher Beiträge
Mit anderen Mitwirkenden zusammenarbeiten, um Anleitungsnotizen zu erstellen, in denen UConn-Studenten und andere Community-Mitglieder rekrutiert werden 7/1 Status: Praktikum genehmigt und Bewerbungen eingehen
Erwartete Signifikanz
Mit diesem Google Summer of Docs-Vorschlag soll die NumPy-Dokumentation erstellt, fehlende Anleitungen auf der Website ergänzt und Mitwirkende an der Dokumentation gewonnen werden. Als Professor für Maschinenbau möchte ich die Dokumentation so segmentieren, dass meine Studenten die Dokumente leicht navigieren und Einführungsleitfäden von praktischen Anleitungen unterscheiden können. Die segmentierte Dokumentation (Tutorial, Anleitung, Referenz und Erläuterung) liefert potenziellen Beitragenden strukturierte Beispiele zum Erstellen neuer Ressourcen. Die vorgeschlagene Dokumentation eignet sich für einen Austausch zwischen neuen und erfahrenen Nutzern, da sie Informationen vermittelt und kommuniziert. Im vorgeschlagenen Leitfaden für die Beratung von Studenten der University of Connecticut wird diese Idee umgesetzt. Wir möchten, dass alle Nutzer die Möglichkeit haben, zu experimentieren, zu lernen und der NumPy-Community beizutreten.
Verweise
- Zugriff auf die Website numpy.org im Juli 2020.
- NumPy-GitHub-Repository
- Das Dokumentationssystem. Divio.com, Stand: Juli 2020.
- Dewey, John. Demokratie und Bildung. Project Gutenberg, August 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.