Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- Matplotlib
- Technischer Redakteur:
- jeromev
- Projektname:
- Matplotlib-Einstiegspfade entwickeln
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Einführung
Der Projektvorschlag von Matplotlib für die diesjährige Google Season of Docs besteht darin, Inhalte zu erstellen, die neuen Nutzern die Einführung in Matplotlib erleichtern. Für die Entwicklung von Matplotlib-Eingabepfaden schlage ich einen alternativen Ansatz vor, der von der aktuellen Dokumentation abweicht. Ich bin eine neue technische Redakteurin in der Branche. Mein Hintergrund liegt jedoch in den Bereichen Bildung und Bildung. Technisches Schreiben und Bildung haben starke Parallelen, die sich auf die Erstellung von Inhalten konzentrieren, die Empathie aufbauen und es Nutzern ermöglichen, ihre Aufgaben mit den bereitgestellten Ressourcen zu erledigen.
In diesem Zusammenhang würde die Matplotlib-Dokumentation von einer Verbesserung profitieren, um Empathie mit neuen Nutzern aufzubauen. Derzeit besteht ein Großteil des Materials aus zufälligen Daten und Bildern ohne Label. Sie eignen sich hervorragend, um die visuellen Elemente und die Funktionen von Matplotlib schnell anzuzeigen. Für Nutzer, die mit Matplotlib noch nicht vertraut sind, ist es jedoch schwierig, die Daten in visuelle Darstellungen umzuwandeln.
Ein Kontext in einem erläuternden Ansatz ist eine Lösung für dieses Problem. Indem wir ein Verfahren aus der Perspektive eines realen Beispiels schreiben, zeigen wir, dass wir die Umgebung verstehen, in der Nutzende arbeiten. Dies verbessert die Beziehung zwischen der Dokumentation und den Nutzern in Bezug auf das Erreichen eines Ziels oder die Erwartung, eine Aufgabe zu erledigen.
Ein Nutzer hat einen konsistenten abgeleiteten Zweck. Beispiel: Ein Data Scientist in einem Schuhunternehmen muss einem Team Kundendaten präsentieren, um Kauftrends im Zeitverlauf zu veranschaulichen. In diesem Fall muss der Nutzer lernen, Matplotlib zu bedienen und die Tools in der Bibliothek zu nutzen, um die anstehende Aufgabe zu erledigen.
Mit zusätzlichem Kontext zur Unterstützung der Dokumentation kann sich ein neuer Nutzer leichter mit dem Thema identifizieren. Der abgeleitete Zweck des Nutzers ist parallel zur Dokumentation. Ich hoffe, dass ich die Vision verwirklichen kann, die Lead Developer Tom Caswell 2017 in einem Interview beschrieben hat: „Wir brauchen jemanden, der gut schreiben kann und Empathie mit den Nutzern hat, der ein 200-seitiges Buch mit einer Einführung in Matplotlib verfasst und das als Haupteintrag in die Dokumentation aufnimmt.“
Alternativer Ansatz des expositorischen Schreibens
Die aktuelle Dokumentation zeigt die Funktionen von Matplotlib, also die Möglichkeiten, die Nutzer mit der Bibliothek haben. Ein Tutorial folgt beispielsweise häufig einem Muster, bei dem die zugrunde liegende Methode nicht erläutert wird.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Häufig wird Nutzern empfohlen, den Code mithilfe von Programmierdokumentation und Support eigenständig auszuführen, um zu verstehen, was passiert. Obwohl ein Programmierverständnis das Verständnis des Themas für Nutzer verbessert, gibt es nur wenig unterstützende Inhalte für die Lernkurve für Transformationen. Das kann eine große Herausforderung sein, da die Dokumentation begrenzt ist.
Zusätzliche Diagramme, Bilder oder andere visuelle Elemente bieten neue Lernmöglichkeiten. Die folgende Struktur eignet sich auch gut als Vorlage für neue Inhalte. Auch Funktionen wie Zusatzinformationen und Kutschenzeichen könnten für das Hinzufügen von nicht textbasierten Bildern oder Grafiken nützlich sein. Manchmal ist die Navigation in Bildern schwieriger, wenn nicht angegeben ist, wie oder wo der Code in die ausgeführte Ausgabe umgewandelt wird. Ich glaube, dass ein starkes visuelles Element fehlt, das das Verständnis der Themen fördern könnte.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Dieser alternative Ansatz, erläuterndes Schreiben für die Dokumentation zu verwenden, birgt enormes Potenzial. Wenn Nutzer eine Vielzahl von Konzepten für Transformationen sehen, können sie die zugrunde liegenden Strategien zur Entwicklung von Visualisierungen für Daten besser erkennen. Dieses Wissen kann Nutzern helfen, innovativ zu sein und die Funktionen zu nutzen, die anhand von Beispielen aus realistischen Anwendungsfällen vorgestellt werden.
Die Beliebtheit von Matplotlib steigt, und die Konsistenz in Bezug auf Benutzerfreundlichkeit und Zugänglichkeit zeugen vom Ruf der Bibliothek. Diese Eigenschaften eignen sich, um Muster und gängige Strategien zu veranschaulichen, die sich nicht nur im Code, sondern auch in der Dokumentation zeigen können. Wenn Matplotlib für Nutzer einfach und standardmäßig zu programmieren ist, was sich in der wachsenden Nutzung und den wachsenden Ressourcen zeigt, kann dies auch für technische Dokumentationen der Fall sein.
Wenn Nutzer auf Probleme stoßen, nutzen sie häufig die Suche, um sie zu lösen. Anstatt die Suche als primäre Navigationsmethode zu verwenden, kann es effektiver sein, wenn Nutzer ihr eigenes Curriculum in der Dokumentation erstellen. In diesem Sinne sucht ein Nutzer nach einer Lösung für sein Problem. Wenn er dann auf ein anderes Problem stößt oder zusätzliche Informationen benötigt, nutzt er die eingebetteten und ausführlichen Links.
Dies würde eine Bottom-Up-Architektur im Organisationssystem erfordern. Für jedes Thema in Matplotlib würde ein umfangreiches Netzwerk von Links zu Themenaffinitäten sowie zu informativen Themen dazu beitragen, ein robustes Netzwerk aufzubauen. In diesem Netzwerk ist es wahrscheinlicher, dass ein Nutzer die Dokumentation weiter nutzt, während er zu seinem Thema navigiert und immer mehr Informationen zu diesem Thema findet.
Hindernisse
Bei einem so umfassenden und detaillierten Projekt gibt es immer Herausforderungen. Als neuer technischer Redakteur in der Branche habe ich nur begrenzte Erfahrung mit der Verwendung von Sphinx und ReST zum Erstellen von Dokumentationen. Ich bin auch ein Anfänger, was Matplotlib und Git angeht. Es wird einige Zeit dauern, diese vier Systeme in Angriff zu nehmen und sie für die Zusammenarbeit und Forschung einzusetzen. Ich muss während der Phase des Aufbaus von Beziehungen in der Community und davor Zeit einplanen, um die notwendige Grundlage für Einstiegspositionen zu schaffen. Sollten in dieser Zeit Probleme mit Konzepten und Grundlagen auftreten, muss ich mich an die Community wenden, um weitere Unterstützung zu erhalten.
Auch die Koordination von Kooperationen über Zeitzonen und Onlineplattformen hinweg wird einige Anpassungen erfordern. Es gibt eine Vielzahl von Kommunikationskanälen, die Menschen in der Branche nutzen. Deshalb ist es wichtig, dass ich in allen Medien erreichbar und ansprechbar bin. Ich werde bei meiner Priorisierung unterschiedlicher Erwartungen durchgehend transparent sein. Obwohl ich erst vor Kurzem damit begonnen habe, solche Aufgaben in der Branche zu übernehmen, bin ich bestrebt, mich selbst zu verantworten und offen für Feedback und Kritik zu sein. Ich habe das Gefühl, dass diese Eigenschaften in allen Bereichen wertvoll sind.
Außerdem ist die Ausweitung von Usability-Tests ein Bereich der Dokumentation, der meiner Meinung nach den Einstiegswegen in Matplotlib zugutekommen würde. Usability-Umfragen zu den Inhalten dienen dazu, ein Nutzerprofil zu erstellen, also Personas. Informationen wie die Erfahrung eines Nutzers, seine Branche und seine bisherigen Schritte zur Fehlerbehebung sind wertvoll. Diese Angaben helfen dabei, die Sprache hinter dem Verfahren zu formulieren. Wenn das Schreiben den Lesern auf ihrem Niveau gerecht wird, werden Inhalte nicht zur reinen Lehrtätigkeit verwendet.
Die größte Herausforderung besteht oft darin, Usability-Tests kontinuierlich durchzuführen. Es ist viel zu häufig, dass während der Inhaltserstellung nur ein einziger Test durchgeführt wird, wenn überhaupt. Regelmäßige Usability-Tests tragen dazu bei, die Erzählung der Inhalte zu steuern. Ich würde mir wünschen, einen Zeitplan festzulegen oder wiederkehrende Usability-Tests mit der Matplotlib-Community durchzuführen.
Fazit
In meiner Freizeit habe ich ein wenig Erfahrung mit Python und Matplotlib. In den letzten Monaten habe ich mir mithilfe der aktuellen Dokumentation und durch meine eigene Neugier etwas beigebracht. Außerdem habe ich in dieser Zeit einige Videos und Mentoren gehabt. Ich habe noch viel zu lernen und noch mehr Raum für Verbesserungen, da ich mein eigenes Programm für die Programmierung zusammenstelle, die mich interessiert.
Nachdem ich die Ideen von Matplotlib und der Community für GSoD gesehen habe, bin ich der Meinung, dass es eine hervorragende Gelegenheit wäre, meine Fähigkeiten als technischer Redakteur zu verbessern und mehr von den Leuten hinter den Kulissen zu lernen. Ich habe das Gefühl, dass dieses Matplotlib-Projekt sowohl bedeutsam als auch für mich in der Ideologie eine Leidenschaft ist.
Bei der Überarbeitung der Bedienungsanleitung möchte ich als Technischer Redakteur Nutzern helfen, die gewünschten Aufgaben zu erledigen, ohne von den verfügbaren Funktionen überwältigt zu werden. Ich glaube, dass die beste Dokumentation weiter wachsen und sich an die Nutzer anpassen sollte und es jedem Nutzer ermöglichen sollte, eigene Lösungen zu finden.