Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- NumPy
- Technischer Redakteur:
- cooperrc
- Projektname:
- NumPy-Dokumentation für den Aufbau einer Community
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Einleitung
NumPy bietet sauberes und schnelles Array-basiertes Computing in einer kostenlosen Open-Source-Softwarebibliothek. Es ist ein grundlegendes Paket im SciPy-Stack für das wissenschaftliche Rechnen [1]. Mehr als 370.000 Projekte werden für effizientes Array-Computing genutzt [2]. NumPy-Nutzende werden von einer neuen Website mit Anwendungen und Fallstudien begrüßt [1]. Wenn neue Nutzende die Dokumentationsseite finden, werden ihnen mehrere „Start Here“-Links und einführende Tutorials angezeigt, die für Einsteiger überwältigend sein können, z. B. NumPy Basics/Byte-Swapping. Ich habe NumPy vor zehn Jahren angefangen, während ich an einer Hochschule fing, NumPy zu benutzen. Ich habe Blogposts, Vortragsnotizen und StackExchange-Antworten zusammengefügt, um nicht die NumPy-Dokumentation durchzugehen. Es gibt derzeit über 360.000 StackExchange-Konversationen, die mit NumPy zu tun haben. Ich kann mir vorstellen, dass andere Nutzende mit NumPy auf ähnliche Weise erfolgreich waren. Die Grundbausteine von Lerntools 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 Nutzende sein. Die Tutorials sollten neuen Nutzenden leicht verständliche Schritte vermitteln und sollen sich mit der Bibliothek vertraut machen [3]. Die Dokumentation sollte neue Nutzer in der NumPy-Community willkommen heißen. Struktur, Tempo und Autoren der Dokumentation müssen einen Ort schaffen, an dem die Forschung und Kommunikation gefördert werden. Mit diesem Vorschlag werden die Lücken in der aktuellen NumPy-Dokumentation organisiert und geschlossen, sodass neue Nutzer informiert und in der Community begrüßt werden.
Das Wissen, das Nutzende kommunizieren, wird durch Tests und Experimente erworben [4,5]. Wissen hängt von der Test- und Auswertungsmethode ab. Inhalte mit klaren Zielen und Anwendungsmöglichkeiten in Anleitungen ermöglichen Nutzern, neue Ideen und Methoden zu testen und zu bewerten. Die Community kann eine Wissensdatenbank aufbauen, um Fähigkeiten, Fakten und Anwendungen zu erweitern. Die Anleitung bietet zwei Vorteile. Erstens haben neue und erfahrene Nutzer klare Ziele beim Testen und Erstellen von Tests. Zweitens haben potenzielle Mitwirkende an der Dokumentation einen Raum, in dem sie ihre Ziele, Methoden und Lösungen kommunizieren können. Die Anleitung erfüllt unmittelbar das Bedürfnis, die NumPy-Dokumentation für neue Nutzende und mögliche Beitragende zugänglicher zu machen. Aktuelles Wissen
John Dewey sagte, die Grundlage des Lernens sei eine echte Erfahrung [4]. Die NumPy-Community hat eine enorme Menge an aufrichtiger Erfahrung, die mit anderen Nutzern geteilt werden kann. Bildung basiert auf Gemeinschaft und Kommunikation. Eine organisierte Dokumentationsseite macht NumPy für neue Nutzer zugänglich. Außerdem wird eine strukturierte Vorlage erstellt, mit der potenzielle Beitragende Erfahrungen in NumPy kommunizieren können.
Es gibt vier weit gefasste Bereiche für die Softwaredokumentation [3]: Tutorial-, Anleitungs-, Erklärungs- und Referenzraum. Die NumPy-Dokumentation enthält eine Reihe von Dokumenten im Tutorial-Bereich, die eine Mischung aus Erklärungs- und Anleitungsinhalten in das Tutorial enthalten. In Tutorials sollte der Fokus auf der Nutzerschulung liegen und einfach zu wiederholende Schritte zur Kommunikation von Ideen umfassen. Die Anleitungen bieten eher zielorientierte Verfahren, die Nutzende in realen Anwendungen anwenden können. Der Erklärungsbereich enthält detaillierte Informationen und detaillierte Dokumentzeichenfolgen in den einzelnen Funktionen. Die aktuelle Anleitung und die Anleitungsbereiche sind nicht klar abgegrenzt und werden manchmal in die Erklärungs- und den Referenzraum eingefügt. Es gibt ein hervorragendes Tutorial für „Absolute Anfänger“ und in „Numpy für Matlab-Nutzer“ finden Matlab-Nutzer eine großartige Referenz zum Erstellen von NumPy-Code. Durch die klare Abgrenzung dieser vier Bereiche wird die Dokumentation klarer.
Lücke in der Wissensdatenbank/unerfüllter Bedarf
Die aktuelle Dokumentation deckt viele wichtige Themen ab, unterscheidet jedoch nicht klar zwischen Tutorial, Anleitung, Erklärung und Referenzbereichen. Das führt zu Verwirrung bei potenziellen Beitragenden. Neue Nutzer können mit Erklärungen und Referenzmaterial im Anleitungsabschnitt überfordert sein und potenzielle Beitragende stehen mit Schwierigkeiten konfrontiert, um einen Beitrag zu leisten. Ich schlage ein zugänglicheres Layout für Neueinsteiger und mögliche Mitwirkende an der Dokumentation vor, mit einem logischen Ablauf bei der Dokumentation und der Verwaltung von Pull-Anfragen für von Nutzern bereitgestellte Anleitungsdokumente durch neue Mitwirkende. Mein langfristiges Ziel ist es, die Dokumentations-Community aufzubauen, damit das Lernen aus der Dokumentation eine Erfahrung mit dem Lernen und Kommunizieren ist. Dieses Modell für die Dokumentation dient als Grundlage für die Bildung in der Praxis für neue Einsteiger und potenzielle Mitwirkende.
Begründung
Dieser Vorschlag für den Sommer von Google Docs ist wichtig für meine pädagogischen und beruflichen Ziele. Ich verwende NumPy und SciPy in allen meinen Kursen. Die Navigation in der aktuellen Dokumentation ist für die Schüler schwierig. Ich möchte Programmieren in Nicht-CS-Hauptfächern nutzen, um Lücken in den aktuellen Tutorials zu organisieren, zu bearbeiten und zu schließen. Anschließend kann ich die Dokumentation als Lehrbuch und als Referenzmaterial für meine Kurse verwenden. Ich habe Dutzende von Tutorials, Übungen und Beispielen mit Python und
Spezifische Ziele
Ich habe drei konkrete Ziele für diesen Vorschlag für den Sommer von Google Docs: 1. Die aktuelle Dokumentation organisieren, 2. Bearbeiten Sie die aktuellen Anleitungen (Erste Schritte, Array-Erstellung, Indexierung, lineare Algebra und NumPy für Matlab), um Referenzinformationen in den Erklärungsraum zu verschieben. 3. Anleitungsmaterialien für Ihre Schüler und Studenten zusammenstellen Jedes spezifische Ziel hat ein erwartetes Ergebnis für den Vorschlag.
Diese drei spezifischen Ziele dienen dazu, die Dokumentation für neue Nutzende ansprechender zu gestalten und potenziellen Beitragenden eine Struktur zu bieten. Die Ziele unterstützen auch das langfristige Ziel, die NumPy-Dokumentations-Community weiter auszubauen. Erwartete Ergebnisse
Ich habe drei erwartete Ergebnisse wie diese: 1. Eine überarbeitete Dokumentationswebseite, die die vier Bereiche klar voneinander trennt: Tutorials, Anleitung, Erklärung und Referenz, 2. neue Tutorials zum Lesen und Schreiben von Arrays, zum Erstellen von Arrays (np.zeros, np.ones, np.block usw.) und für die elementweise vs. lineare Algebraoperation in NumPy und 3. eine kuratierte Anleitungsfläche.
Diese erwarteten Ergebnisse helfen neuen Nutzern, Dokumente durchzugehen, potenziellen Dokumentationspersonen mit klaren Stilen und Formaten zur Verfügung zu stellen, aktuelle Anleitungen kürzer und leichter verständlich zu machen, Erläuterungen in einen separaten Abschnitt zu verschieben und neue Mitwirkende können kleine Anwendungsfälle zum Anleitungsabschnitt beisteuern, ohne eine gesamte Sphinx-Dokumentation erstellen zu müssen. Wir möchten unsere Lehr- und Lern-Community weiter ausbauen.
Neue an der Dokumentation beteiligte Personen können für Millionen von Nutzern kleine Anwendungsfälle bereitstellen, ohne die gesamte Sphinx-Dokumentation erstellen zu müssen. Wir möchten unsere Lehr- und Lern-Community weiter ausbauen. Diese vorgeschlagene Dokumentation ahmt aktuelle Open-Source-Dokumentationen wie Matplotlib oder Divio nach. Neue Nutzer und potenzielle Beitragende können NumPy in ihrem Fachgebiet und in ihrer Software leichter anwenden.
Der Zeitplan für das Projekt läuft vom 14.09.-30.11. Der erste Schritt besteht darin, die Dokumentation zu erstellen und die Inhalte der aktuellen Tutorials in Anleitungen, Anleitungen und Erläuterungsinhalte aufzuteilen. Dies wird in den ersten fünf Wochen des Projekts im Rahmen der Ergebnisse 1 und 2 der Überarbeitung der Website und der Anleitungen erfolgen. Die vorgeschlagene Dokumentationsorganisation wird in der vorgeschlagenen Dokumentation unten gezeigt.
Vorgeschlagene Dokumentation:
i.Tutorials:
- Absolute Grundlagen für Einsteiger (Entfernung der Installation, kann pandas-Import/-Export durch numpy.loadtxt ersetzt werden?)
- Link zu „Was ist NumPy?“
- Link zur grundlegenden Installationsanleitung
- Kurzanleitung (nachfolgend zur Python-Anleitung)
- Mit NumPy-Arrays arbeiten
- Array-Erstellung (np.zeros, np.ones, np.block usw.) (Schreiben: mittlere/niedrige Priorität)
- Elementweise Operationen (+,-,*,/) und lineare Algebra-Operationen (+,-,@, linalg.solve) (write:mit-Priorität)
- Daten mit Numpy lesen und schreiben (schreiben: hohe Priorität)
- Indexierung
ii. Anleitungen:
- Lineare Algebra auf n-dimensionalen Arrays (würde gern die Überschriften und Beschreibungen bearbeiten und den Titel eventuell in „Bildverarbeitung mit der linearen Algebra von Numpy“ ändern“)
- Link zu numpy-tutorials-Anleitungen (laufende Aufgaben)
iii. Was bedeuten diese Regeln?
- Datentypen
- E/A mit Numpy
- Indexierung
- Mit Nachrichten an alle
- Byte-Austausch
- Strukturierte Arrays
- Benutzerdefinierte Arraycontainer schreiben
- abgeleitete Klassen von ndarray
- Sonstige
iv. Referenzraum:
- Glossar
- Numpy API-Referenz
- Numpy für Matlab-Nutzende (die Äquivalenztabelle ist eine gute Referenztabelle, aber die Array-/Matrixdiskussion ist ablenkend und scheint veraltet zu sein)
Ich schlage vor dem Abschluss dieser Google-Staffel von Google Docs Folgendes vor:
- Eine überarbeitete Dokumentationswebseite, die die vier Bereiche „Tutorials“, „Anleitung“, „Erläuterung“ und „Referenz“ klar voneinander trennt
- Neue Anleitungen für: Arrayerstellung (np.zeros, np.ones, np.block usw.), elementweise Operationen (+,-,*,/) und lineare Algebra-Operationen (+,-,@, linalg.solve) sowie Daten mit Numpy (hohe Priorität) lesen und schreiben
- Empfehlung von Anleitungsdokumenten, um mehr Nutzerbeiträge zu erzielen und die Ziele der Community im Unterricht und Lernen zu fördern
Für jedes Ergebnis sind eine Reihe von Schritten aufgeführt, die unten in den Tabellen für Ergebnisse 1 bis 3 aufgeführt sind. Während die vorgeschlagene Dokumentation zur Überprüfung eingereicht wird, wird das Tutorial „Lese-/Schreib-Arrays“ mit hoher Priorität als Pull-Anfrage als Teil von Ergebnis 2 gesendet. Während der Überprüfung der überarbeiteten Website und der aktualisierten Anleitung zum Lesen/Schreiben von Arrays werde ich mit dem Schreiben einer Anleitung zum Erstellen von Arrays mit NumPy-Funktionen beginnen, z.B. np.ones, np.zeros, np.diag. Die verbleibende Zeit wird verwendet, um auf Probleme mit Pull-Anfragen zu reagieren und das Tutorial für Rang 3 zu schreiben: Elementweise und lineare Algebraoperationen in Python.
Als drittes Ergebnis sollen Studenten der University of Connecticut dazu aufgefordert werden, eine Dokumentation im numpy-tutorials-Repository zu erstellen. Bei den eingereichten Anleitungen oder Anleitungsdokumenten handelt es sich um Jupyter Notebooks, die mithilfe von NumPy technische Probleme lösen. Ich werde einige meiner Kursnotizen/Beispiele verwenden, um ein Beispielnotizbuch einzureichen. Ich werde den Schülern raten, sich beim Erstellen einer Vorlage und eines Framing-Schemas an das Layout und die Struktur zu halten. Dieses Ergebnis ist eine echte Erfahrung für die Schüler, Konzepte und Lösungen einem breiteren Publikum zu vermitteln. Dies ist eine großartige Gelegenheit für Schüler, sich in der NumPy-Community zu engagieren und zu lernen.
Ergebnis 1: Website-Liefergegenstand überarbeiten 1.1.11/1. Auf Kommentare/Vorschläge antworten und PR-Überarbeitung mit Ergebnis überarbeiten/30
Ergebnis 2: Tutorials überarbeiten Ergebnisdatum Anleitungen Überarbeitungsrangfolge 9/21 lesen Aktuellen Inhalt der Anleitung in Anleitungs- und Erklärungsbereiche aufteilen 10/1 Rang 1: Lese-/Schreib-Arrays 10/10 schreiben PR an GitHub zur Trennung und Überarbeitung 10/20 senden Rang 2: Array-Erstellung: linear 11/15/3 PR für Elemental-1-PR1 schreiben
Vorgeschlagene Reihenfolge der Überarbeitungen der Anleitung (kann sich je nach Mentor/Community ändern):
Derzeit leere Seite mit Lese-/Schreib-Arrays
Array-Erstellung (np.zeros, np.ones, np.block usw.) Nicht vorhanden: Hilft neuen Nutzern, die gängigen Tools zur Array-Erstellung/-Interaktion zu erklären und vorzuführen
Elementweise und lineare Algebra-Operationen (+,-,*,/ und +,-@,linalg.solve) existiert nicht: Dies ist besonders hilfreich für 1. Matlab-Nutzer*innen und 2. Personen, die die lineare Algebra verwenden (maschinelles Lernen, lineare Regression usw.)
Ergebnis 3: Ausgewählte Anleitungsfläche Liefergegenstand Externer Link(Ausgabe/Beispiel)
Anleitungsbeispiel erstellen (Kandidat: So ermitteln Sie die natürliche Häufigkeit von Gitarrensaiten 10/20)
Anleitungsvorlage für neue Beitragende erstellen 10/1 in Bearbeitung Anleitungsvorlage PR und Rahmung möglicher Beitrag
Zusammenarbeit mit anderen Mitwirkenden an der Erstellung von Anleitungs-/Lern-Notizbüchern1 Anwerbung von anderen UConn-Schülern und Anträgen für den Community-Status1
Erwartete Signifikanz
In diesem Vorschlag für den Google Summer of Docs wird die NumPy-Dokumentation erstellt, fehlende Anleitungen von der Website ergänzt und Mitwirkende an der Dokumentation gewinnen. Als Professorin für Maschinenbau habe ich vor, die Dokumentation so zu segmentieren, dass meine Studenten die Dokumente navigieren und einführende oder praktische Anleitungen leicht finden können. Die segmentierte Dokumentation (Tutorial, Anleitung, Referenz und Erklärung) enthält strukturierte Beispiele zur Erstellung neuer Ressourcen für potenzielle Beitragende. Die vorgeschlagene Dokumentation eignet sich als Geben und Nehmen, durch Informationen und Kommunikation für neue und erfahrene Nutzende. Die vorgeschlagene Formulierungsberatung durch Studenten der University of Connecticut wird diese Idee zum Lehren und Kommunizieren in die Praxis umsetzen. Wir möchten, dass alle Nutzer Raum zum Experimentieren und Lernen haben und der NumPy-Community beitreten können.
Verweise
- NumPy.org-Website, Zugriff seit Juli 2020.
- NumPy GitHub-Repository.
- Das Dokumentationssystem. Divio.com, Stand: 7. Juli 2020.
- Dewey, John. Demokratie und Bildung. Project Gutenberg, August 2015.
- Dewey, John. Mission von Certainty George Allen und Unwin Limited 06.06.2005.