Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- Matplotlib
- Technischer Redakteur:
- Jeromev
- Projektname:
- Matplotlib-Eintragspfade entwickeln
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Einführung
Matplotlibs Projektvorschlag für die diesjährige Google Season of Docs umfasst das Erstellen von Inhalten, mit denen Matplotlib neuen Nutzern vorgestellt wird. Ich schlage für die Entwicklung von Matplotlib-Eintragspfaden einen alternativen Ansatz zur aktuellen Dokumentation vor. Ich bin ein neuer technischer Redakteur in der Branche, habe jedoch in der Bildung und bildungsnahen Bereichen gearbeitet. Technisches Schreiben und Bildung haben starke Parallelen, die sich auf das Erstellen von Inhalten konzentrieren, die Empathie aufbauen und Nutzenden ermöglichen, ihre Aufgaben mithilfe der bereitgestellten Ressourcen zu erledigen.
In diesem Kontext würde die Matplotlib-Dokumentation durch eine Verbesserung beim Aufbau von Empathie mit neuen Nutzenden profitieren. Ein Großteil des Materials besteht derzeit aus zufälligen Daten und Bildern ohne Label. Sie eignen sich hervorragend zur schnellen Darstellung der visuellen Elemente und Funktionen von Matplotlib. Im Anwendungsfall einer Person, die neu bei Matplotlib ist, ist es jedoch schwierig, die Umwandlung von Daten in visuelle Elemente zu durchlaufen.
Ein Kontext in einem expositorischen Ansatz ist eine Lösung für dieses Hindernis. Durch die Formulierung eines Verfahrens anhand eines realen Beispiels demonstrieren wir ein Verständnis der Umgebung, in der Nutzende arbeiten. Dies verbessert die Beziehung zwischen Dokumentation und Nutzenden in Bezug auf das Erreichen eines Ziels oder der Erwartungen an die Ausführung einer Aufgabe.
Nutzende verfolgen einen einheitlichen Zweck. Beispielsweise muss ein Data Scientist bei einem Schuhunternehmen einem Team Kundendaten zur Verfügung stellen, um die Einkaufstrends im Zeitverlauf zu veranschaulichen. In dieser Situation muss der Nutzer lernen, mit Matplotlib zu navigieren, und die Tools in der Bibliothek nutzen, um die vorliegende Aufgabe zu erledigen.
Mit zusätzlichem Kontext für die Dokumentation können sich neue Nutzer möglicherweise besser mit dem Thema identifizieren. Der abgeleitete Zweck der Nutzenden ist parallel zur Dokumentation. Ich hoffe, auf die Vision zu arbeiten, die Lead Developer Tom Caswell 2017 in einem Interview erörterte: „eine Person zu haben, die tatsächlich schreiben und Empathie für die Nutzenden hat, ein 200-seitiges Buch mit dem Titel „Intro to Matplotlib“ durchgehen und schreibe und das als Haupteintrag in die Dokumentation nehmen soll.“
Alternativer Ansatz des Schreibens von Expositions
In der aktuellen Dokumentation werden die Funktionen von Matplotlib demonstriert, d.h. die Dinge, die ein Nutzer mit der Bibliothek tun kann. Beispielsweise folgt ein Tutorial oft einem Muster, bei dem die zugrunde liegende Methode nicht erläutert wird.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
In der Dokumentation und dem Support zur Programmierung wird einem Nutzer häufig empfohlen, den Code eigenständig auszuführen, um zu verstehen, was passiert. Obwohl die Denkweise der Programmierung das Verständnis der Nutzenden verbessert, hat die Lernkurve für Transformationen wenig unterstützende Inhalte. Da die Dokumentation begrenzt ist, kann dies eine überwältigende Herausforderung darstellen.
Wenn Sie zusätzliche Diagramme, Bilder oder andere visuelle Elemente zur Verfügung stellen, können Sie neue Lernmöglichkeiten schaffen. Die nachstehende Struktur eignet sich ebenfalls gut als Vorlage für neue Inhalte. Auch nicht textbasierte Bilder oder Grafiken können von Funktionen wie Zusatzinformationen und Coachmark-Elementen profitieren. Manchmal ist die Navigation in Bildern schwieriger, ohne dass angegeben wird, wie oder wo der Code in die Ausführung der Ausgabe umgewandelt wird. Ich denke, dass ein starkes visuelles Element fehlt, das ein besseres 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 birgt ein enormes Potenzial für die Verwendung von Expository-Schreiben für die Dokumentation. Da Nutzende eine Vielzahl von Transformationen begegnen, könnten sie die zugrunde liegenden Strategien zur Entwicklung von Datenvisualisierungen besser identifizieren. Dieses Wissen kann Nutzern helfen, Innovationen zu entwickeln und die Funktionen, die anhand von Beispielen in realistischen Anwendungsfällen präsentiert werden, zu nutzen.
Da Matplotlib immer beliebter wird, sind Beständigkeit und Nutzerfreundlichkeit ein Beweis für den Ruf der Bibliothek. Diese Eigenschaften eignen sich zur Veranschaulichung von Mustern und gängigen Strategien, die nicht nur im Code, sondern auch in der Dokumentation auftauchen können. Wenn Matplotlib für Nutzer einfach und standardmäßig zu programmieren ist, was sich an der zunehmenden Nutzung und wachsenden Ressourcen ablesen lässt, kann es auch für die technische Dokumentation verwendet werden.
Wenn Nutzende auf Probleme stoßen, verwenden sie zur Lösung häufig die Suche. Anstatt sich auf die Suche als primäre Navigationsmethode zu verlassen, kann es wirkungsvoller sein, wenn Nutzende innerhalb der Dokumentation einen eigenen Lehrplan erstellen. In diesem Sinne suchen Nutzende nach einer Lösung für ihr Problem. Wenn sie auf ein anderes Problem stoßen oder zusätzliche Informationen wünschen, verwenden sie durchgehend eingebettete und ausführliche Links.
Dies würde eine Bottom-up-Architektur im Organisationssystem beinhalten. Zu jedem Thema in Matplotlib würde ein umfangreiches Netzwerk aus Links zu Themen mit gemeinsamen Interessen sowie Informationen dazu beitragen, ein stabiles Netzwerk aufzubauen. In diesem Netzwerk ist es wahrscheinlicher, dass Nutzende die Dokumentation weiterhin verwenden, wenn sie zu ihrem Thema navigieren und mehr und mehr Informationen zu diesem Thema suchen.
Hindernisse
Bei einem so umfassenden und detaillierten Projekt gibt es immer Herausforderungen. Als neuerer technischer Redakteur in der Branche habe ich nur begrenzte Erfahrung mit Sphinx und ReST, um Dokumentationen zu schreiben. Ich bin auch ein Neuling, wenn es um Matplotlib und Git geht. Es wird Zeit, diese vier Systeme in Angriff zu nehmen und sich mit ihrer Verwendung für die Zusammenarbeit und Forschung vertraut zu machen. Ich muss während der Community-Bonding-Phase und früher Zeit einteilen, um die notwendige Grundlage für Einstiegspfade zu schaffen. Wenn ich in dieser Zeit Probleme mit Konzepten und Grundlagen habe, muss ich mich an die Community wenden, um weitere Unterstützung zu erhalten.
Auch die Koordination der Zusammenarbeit über Zeitzonen und Onlineplattformen hinweg wird einige Anpassungen erfordern. Menschen in der Branche nutzen verschiedene Kommunikationswege. Daher ist es wichtig, dass ich über alle Medien zugänglich und zugänglich bin. Ich werde bei der Priorisierung unterschiedlicher Erwartungen immer transparent sein. Obwohl ich gerade erst mit solchen Tätigkeiten in der Branche angefangen habe, bin ich in meine Verantwortung investiert und bin offen für Feedback und Kritik. Diese Qualitäten sind für mich in jedem Bereich wertvoll.
Außerdem ist die Erhöhung der Usability-Tests ein Dokumentationsabschnitt, von dem ich glaube, dass die Einstiegspfade von Matplotlib von Nutzen sein würden. Die Durchführung von Umfragen zur Verwendbarkeit der Inhalte dient dem Zweck, ein Profil von Nutzenden, d.h. Personas, bereitzustellen. Informationen wie die Erfahrung eines Nutzers, seine Branche und der Verlauf der Fehlerbehebung sind wertvoll. Diese Teile bilden die Sprache hinter dem Verfahren. Wenn Texte den Lesern auf ihrem Niveau entsprechen, sind Inhalte nicht nur zum Lehren gedacht.
Große Schwierigkeiten entstehen oft dadurch, dass fortlaufende Usability-Tests durchgeführt werden. Es kommt viel zu häufig vor, dass während der Entwicklung von Inhalten nur eine Testinstanz durchgeführt wird, wenn überhaupt. Regelmäßige Usability-Tests fördern die Erzählung des Inhalts. Ich würde gerne einen Zeitplan erstellen oder regelmäßige Usability-Tests mit der Matplotlib-Community durchführen.
Fazit
Ich habe in meiner Freizeit ein wenig Erfahrung mit Python und Matplotlib. In den letzten Monaten habe ich mir etwas beigebracht, dank der aktuellen Dokumentation und meiner eigenen Neugier. In dieser Zeit hatte ich auch ein paar Videos und Mentoren. Ich habe immer noch viel zu lernen und noch mehr Raum für Verbesserungen, wenn ich meinen eigenen Programmierplan erstelle, für den ich mich interessiere.
Ich habe mir die Ideen angesehen, die Matplotlib und die Community für GSoD haben, und ich bin der Meinung, dass es eine großartige Erfahrung wäre, meine Fähigkeiten als technischer Redakteur zu verbessern und die Chance zu erhalten, mehr von den Leuten hinter den Kulissen zu lernen. Ich habe das Gefühl, dass dieses Matplotlib-Projekt sowohl sinnvoll als auch etwas ist, für das ich mich im Bereich der Ideologie begeistere.
Als technische Redakteurin möchte ich den Nutzer bei der Überarbeitung des Nutzungsleitfadens unterstützen, damit er die gewünschten Aufgaben erledigen kann, ohne von den verfügbaren Funktionen überwältigt zu werden. Ich bin der Meinung, dass die beste Dokumentation weiter wachsen und sich an die Nutzenden anpassen wird und jedem Nutzenden die Möglichkeit geben würde, zu ihren eigenen Lösungen zu navigieren.