Bokeh-Projekt

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:
Bokeh
Technischer Redakteur:
vis_verborum
Projektname:
Erstellen, Lesen, Teilen: Bokeh-Dokumentation optimieren
Projektlänge:
Standardlänge (3 Monate)

Projektbeschreibung

Erstellen, lesen, teilen: Dokumentation von Bokeh optimieren

1. Zusammenfassung

Bokeh ist ein äußerst leistungsstarkes Tool zum Erstellen interaktiver, browserbasierter Visualisierungen mit Python. Es hat eine beträchtliche Nutzerbasis (502.000 Conda-Downloads pro Monat, 855.000 PyPi-Downloads) und eine große Anzahl von Mitwirkenden (455 Mitwirkende auf GitHub). Es überrascht nicht, dass Bokehs umfangreiche Dokumentation organisch gewachsen ist. Das macht sie an manchen Stellen inkonsistent, schwer zugänglich und kompliziert.

Die Season of Docs von Google bietet eine einzigartige Gelegenheit, die Struktur und den Inhalt der Bokeh-Dokumentation gezielt zu überprüfen und zu überarbeiten und dafür zu sorgen, dass die Dokumentation und die zugehörigen Tools und Workflows zukunftssicher sind.

Ich habe Open-Source-Projekte mit Python und Sphinx programmiert und dokumentiert (zuletzt: PyZillow und PyPresseportal). Was mich aber zu einer besonderen Teilnehmerin der Google Season of Docs macht, ist mein journalistischer Hintergrund: Ich habe mehr als 13 Jahre in Redaktionen gearbeitet, davon viele Jahre als Chefredakteurin und Verfechterin des digitalen Wandels. Neben meinen journalistischen Aufgaben hatte ich zunehmend Verantwortung beim Entwerfen und Dokumentieren neuer digitaler Tools und Stilguides sowie beim Trainieren von Mitarbeitern der Redaktion.

Nachdem ich vor Kurzem von Europa in die USA gezogen bin, habe ich mich entschieden, neue Wege zu finden, um meine Begeisterung für Kommunikation und Programmieren zu kombinieren. Ich fand, dass das technische Schreiben die optimale Kombination aus meinen schriftlichen und technischen Fähigkeiten ist. In diesem Vorschlag werde ich erläutern, wie ich die Dokumentation von Bokeh nutzen werde, um die Dokumentation von Bokeh zu optimieren: Ich erleichtere das Erstellen und leistet einen Beitrag zur Dokumentation, indem ich das Lesen der Dokumentation und das Teilen der Dokumentation mit anderen einfacher mache.

2. Aktuelle Situation

Die offizielle Dokumentation von Bokeh besteht aus den folgenden Einheiten:

  • Dokumentation zur Beschreibung: Installationsanleitung, Nutzerhandbuch, Entwicklerhandbuch, Versionshinweise
  • Galerie und Demos (interaktive Beispiele mit Quellcode)
  • Referenzleitfaden (Dokumentation auf Grundlage von Docstrings)
  • Anleitung (umfangreiche Sammlung von Jupyter-Notebooks, gehostet auf mybinder.org)
  • Docstrings und Modellhilfe für IDEs
  • Beispiele und READMEs im Projekt-Repository

Außerdem finden Sie im Bokeh-Supportforum und auf Stack Overflow eine Fülle von Informationen, wo die Bokeh-Entwickler aktiv Fragen von Nutzern beantworten, sowie im Bokeh-Medium-Blog.

Die meisten Webseiten der Dokumentation werden mit Sphinx erstellt, wobei mehrere Standard- und benutzerdefinierte Sphinx-Erweiterungen verwendet werden. Das Referenzhandbuch wird beispielsweise aus docstrings mit Erweiterungen wie „autodoc“ und dem benutzerdefinierten „bokeh_autodoc“ generiert. Da es sich um biologisch angebaute Dokumentation handelt, enthält sie Redundanzen und Inkonsistenzen.

Eines der ersten Dinge, die mir bei der Analyse der vorhandenen Dokumentation aufgefallen sind, waren die fehlenden klaren Stilrichtlinien für das Verfassen von Dokumentationen. Das Bokeh-Entwicklerhandbuch enthält einige grundlegende Anweisungen. Dieses Dokument enthält jedoch nur wenige Hinweise zum Stil, insbesondere in Bezug auf Dokumentation, die über docstrings hinausgeht. Stilistische und strukturelle Probleme erschweren es daher vor allem Neulingen, auf die Informationen in den Dokumenten zuzugreifen.

Beispiel:

Die Dokumentations-Landingpage von Bokeh ist ziemlich kurz und enthält keine Informationen zu allen verfügbaren Ressourcen. Die umfangreiche Bibliothek mit Docstrings und Modellhilfefunktionen, die Supportforen, die Demos oder der Medium-Blog werden nicht erwähnt. Das erschwert auch neuen Nutzern den Einstieg in Bokeh.

3. Ziele

Um die elfwöchige Entwicklungsphase der Dokumentation möglichst effizient zu nutzen, konzentriere ich mich auf drei Hauptelemente:

3.1. Verbesserungen beim Erstellen von Dokumenten

Der Großteil der Bokeh-Dokumentation wird von Mitwirkenden verfasst, die die Dokumentation als Teil von Pull-Requests für neue Funktionen und Fehlerkorrekturen einreichen. Während ich einen Teil der Entwicklungsphase der Dokumentation zum Bearbeiten und Refaktorisieren der vorhandenen Dokumente nutze, werde ich den Schwerpunkt darauf legen, die Workflows zum Erstellen und Pflegen der Dokumentation zukunftssicher zu gestalten: Es sollte für Mitwirkende so einfach wie möglich sein, einen durchgängig hohen Dokumentationsstandard beizubehalten.

Ich werde dies mit zwei Ansätzen erreichen:

  • Ich werde eine Reihe praktischer, einfacher Stilrichtlinien erstellen, die in das bestehende Entwicklerhandbuch aufgenommen werden sollen. Diese Richtlinien beziehen sich auf Stil, Grammatik und Struktur. Außerdem werde ich interne Kommunikationskanäle wie Slack nutzen, um dafür zu sorgen, dass die Bokeh-Entwickler über die Stilrichtlinien informiert sind. Außerdem biete ich Einzelschulungen und Fragerunden für das Team an.
  • Ich werde mit dem Kernteam zusammenarbeiten, um eine optimale Reihe von Tools für die Qualitätskontrolle der Dokumentation zu finden, die den vorhandenen Bokeh-Workflows für PRs (Pull-Requests) und CI (Continuous Integration) hinzugefügt wird. Je nach den Anforderungen des Teams kann dies bedeuten, dass Tools wie pydocstyle, proselint oder sphinxcontrib-spelling zur Bokeh-Testsuite, zur Pre-Commit-Einrichtung oder zu GitHub-Aktionen hinzugefügt werden. Ich habe den GitHub-Aktionen eines meiner eigenen Open-Source-Projekte einen funktionierenden Proof of Concept hinzugefügt.

3.2. Bessere Lesbarkeit der Dokumente

Das Ziel einer guten Dokumentation besteht darin, es aktuellen und potenziellen Nutzern zu erleichtern, genau die richtigen Informationen zu finden und diese Informationen so effizient wie möglich zu nutzen.

Schlüsselfaktoren für die Nutzungsfreundlichkeit eines Textes sind der Stil und die Struktur: Wenn die Dokumentation in einem klaren, einheitlichen Stil verfasst wird, können die Lesenden Informationen schnell erfassen, ohne Ablenkungen und überflüssige Sprache. Eine einfache und transparente Struktur der Dokumentation macht es leicht, relevante Informationen schnell zu finden.

Ich werde mich auf beide Bereiche konzentrieren, wobei der Schwerpunkt auf der Nutzerfreundlichkeit für neue Nutzer liegt. Dazu gehört eine gründliche Überprüfung der narrativen Dokumentation, die sich auf die Bedienungsanleitung konzentriert. Außerdem überarbeite ich die Landingpage der Dokumentation, um verschiedene Zielgruppen klarer anzusprechen und dafür zu sorgen, dass jeder Nutzer schnell die richtigen Ressourcen findet.

Genau wie bei der Verbesserung der Erstellung von Dokumenten, die oben beschrieben wurde, werde ich mich darauf konzentrieren, eine Grundlage für zukünftige Verbesserungen und kontinuierlich hohe Standards für die Bokeh-Dokumentation zu schaffen.

3.3 Verbesserte Freigabe von Dokumenten

Immer mehr Diskussionen über Bokeh finden auf Drittanbieterplattformen statt. Viele dieser Plattformen verwenden Metadaten wie OpenGraph von Facebook, um detaillierte Vorschauen von Links einzubinden. OpenGraph wird von Diensten wie Facebook, Twitter, LinkedIn, Slack und iMessage verwendet. Das Discourse-Forum von Bokeh verwendet OpenGraph, um Linkvorschauen zu rendern.

Um diese Technologie zu nutzen, füge ich den von Sphinx generierten Webseiten von Bokeh Metadaten hinzu, wie in Problem #9792 beschrieben. Am effizientesten wäre die Verwendung einer dedizierten Sphinx-Erweiterung. Vor einigen Tagen wurde die allererste Version einer Sphinx-Erweiterung für OpenGraph-Daten auf GitHub veröffentlicht. Ich werde einen Teil der Entwicklungsphase der Dokumentation nutzen, um diese Erweiterung für die Verwendung mit der Bokeh-Dokumentation zu verbessern.

Außerdem habe ich einen Proof of Concept erstellt, den ich in einem meiner eigenen Open-Source-Projekte, PyPresseportal, erfolgreich verwende. Mit dieser Erweiterung werden automatisch relevante Informationen wie Titel, Beschreibung, Bild und URL erfasst. Diese Informationen werden dann als OpenGraph-Tags in den von Sphinx generierten HTML-Code eingefügt.

Ein nächster Schritt bei der Entwicklung dieser Erweiterung wäre die Einführung benutzerdefinierter Anweisungen zum manuellen Definieren von OpenGraph-Metadaten (ähnlich den vorhandenen „meta“-Anweisungen von docutil). Automatisch generierte Metadaten werden nur als Fallback verwendet, falls keine manuell eingegebenen Daten verfügbar sind.

Die Unterstützung strukturierter Daten ist viel komplexer, daher konzentriere ich mich hauptsächlich auf das Einbeziehen hochwertiger OpenGraph-Metadaten in die Dokumentation von Bokeh. Alle Arbeiten zur Unterstützung von OpenGraph legen gleichzeitig die Grundlage für die Unterstützung strukturierter Daten.

Mitglieder der Sphinx- und ReadTheDocs-Community haben Interesse an der Entwicklung von Erweiterungen für OpenGraph und strukturierte Daten geäußert (z. B. in den Issues #1758 und #5208). Ich werde eng mit ihnen zusammenarbeiten.

4. Ergebnisse

Zusammenfassend erwartet mich Folgendes von der Season of Docs:

  • Stilrichtlinien für die Bokeh-Dokumentation
  • Überarbeitete PR- und CI-Workflows mit automatisierter Dokumentationsqualitätskontrolle
  • Bearbeitetes und umstrukturiertes Nutzerhandbuch
  • Überarbeitete Landingpage für die Dokumentation
  • OpenGraph-Metadaten auf den Webseiten der Dokumentation und eine funktionierende Sphinx-Erweiterung

Außerdem werde ich auf meiner persönlichen Website oder in meinem Medium-Blog oder im Medium-Blog von Bokeh einen „Doclog“ führen, um meine Reise durch die Season of Docs von Google zu dokumentieren. Dieser dient auch als Grundlage für den Projektbericht für Google. Ich werde alle Arbeiten so transparent wie möglich in Form von GitHub-Problemen und Pull-Anfragen erledigen.

5. Zeitachse

Vor der Community-Bonding-Phase: Ich nehme bereits aktiv an mehreren Diskussionen über das GitHub-Repository von Bokeh teil und hatte Kontakt mit Bryan Van de Ven und Pavithra Eswaramoorthy, den Mentoren von Bokeh für die Season of Docs von Google. Ich werde weiterhin aktiv an der Diskussion über Bokeh teilnehmen und mich auch weiter mit Bokeh vertraut machen, indem ich Visualisierungen erstelle und veröffentliche.

Phase des Community-Aufbaus (17. August bis 13. September):

  • Das Kernteam kennenlernen und den Projektplan im Austausch mit Mentoren optimieren
  • Einen Zeitplan und Kommunikationskanäle für regelmäßige Berichte und Feedback mit Mentoren einrichten
  • Seien Sie aktiv in der Slack-Gruppe von Bokeh, um alle interessierten Bokeh-Mitarbeiter über die Season of Docs von Google und die Ziele der Entwicklungsphase zu informieren.
  • Feedback von Bokeh-Mitwirkenden einholen, um den Plan für die Phase der Dokumententwicklung weiter zu optimieren

Phase der Dokumententwicklung

Woche 1, 14.–20. September:

  • Prüfung und Bearbeitung der narrativen Dokumentation beginnen
  • Mit der Erstellung von Stilrichtlinien beginnen

Woche 2, 21.–27. September:

  • Weiter an den Stilrichtlinien arbeiten
  • Bearbeitung der narrativen Dokumentation fortsetzen
  • Überarbeitung der Dokumentations-Landingpage

Woche 3, 28. September bis 4. Oktober:

  • Stilrichtlinien festlegen
  • Landingpage für die Dokumentation fertigstellen

Woche 4, 5. bis 11. Oktober:

  • Bearbeitung der Dokumentation des Narrativs abschließen
  • Mit dem Bokeh-Kernteam über die Integration von Tools zur Dokumentenqualitätskontrolle in PR-/CI-Workflows sprechen

Woche 5, 12. 10. bis 18. 10.:

  • Einrichtung einer Fragerunde mit Bokeh-Mitarbeitern in Slack, um Stilrichtlinien, Verbesserungen an der narrativen Dokumentation und PR-/CI-Workflows zu besprechen
  • Den vorhandenen Proof of Concept für OpenGraph-Metadaten in eine implementierbare Sphinx-Erweiterung umwandeln
  • Stilrichtlinien basierend auf dem Feedback aus der Fragerunde mit Bokeh-Beitragenden überarbeiten

Woche 6 (19.10.–25.10.):

  • Tests von Tools für die Dokumentenqualitätskontrolle in PR- und CI-Workflows beginnen
  • Fortsetzung der Entwicklung der Sphinx-Erweiterung für Metadaten

Woche 7, 26. 10. bis 1. 11.:

  • Sphinx-Erweiterung testen
  • Zweite Fragerunde mit Bokeh-Mitarbeitern auf Slack
  • Liefergegenstände basierend auf dem Feedback aus der zweiten Fragerunde überarbeiten

Woche 8, 2. – 8. November:

  • Sphinx-Erweiterung bereitstellen und verbesserte narrative Dokumentation und Dokumentations-Landingpage veröffentlichen

Woche 9, 9.11.–15.11.:

  • Tools zur Dokumentqualitätskontrolle in PR- und CI-Workflows bereitstellen
  • Aktualisieren und veröffentlichen Sie den Entwicklerleitfaden, um Stilrichtlinien und Ergänzungen für den PR- und CI-Workflow hinzuzufügen.

Woche 10, 16.11. bis 22.11.:

  • Verbleibende Aufgaben abschließen

Woche 11, 23. bis 29. November:

  • Projektbericht verfassen
  • Projektbewertung verfassen

Phase der Projektfinalisierung

Woche 12, 30. November bis 5. Dezember:

  • Projektbericht fertigstellen und einreichen

Woche 13, 3. Dez. bis 10. Dez.:

  • Projektbewertung fertigstellen und einreichen

Nach dem Ende der Google Docs-Saison gilt Folgendes:

  • Ich hoffe, dass ich weiterhin an der Entwicklung von Bokeh beteiligt sein und an der Bokeh-Dokumentation arbeiten kann.
  • Ich werde die Entwicklung einer Sphinx-Erweiterung für OpenGraph-/Strukturierte-Daten-Metadaten fortsetzen.
  • Ich hoffe, dass ich meine journalistische Erfahrung und mein bestehendes Netzwerk nutzen kann, um Bokeh als Tool für die Datenjournalismus zu bewerben. Zum Beispiel, indem Sie über Bokeh für journalistische Zielgruppen schreiben oder Konferenzvorträge über die Verwendung von Bokeh in journalistischen Umgebungen halten.

6. Über mich

Ich bin ursprünglich Journalistin und habe Erfahrung mit Fernseh-, Online- und Radionachrichten. Durch meine Tätigkeit als Chefredakteur und Reporter im Fernsehen und in digitalen Nachrichten habe ich jahrelange Erfahrung im Schreiben und Bearbeiten. Gleichzeitig habe ich an mehreren Projekten zur digitalen Transformation und Automatisierung gearbeitet. Ich habe zahlreiche Handbücher zu digitalen Tools und Workflows sowie Stilguides und Kommunikationsstrategien für digitale Nachrichtenmarken verfasst. Außerdem habe ich Teammitglieder in der Verwendung dieser Tools geschult.

Die Schnittstelle zwischen Kommunikation und Technologie hat mich schon immer angezogen. Als ich mit Python programmiert habe, hat sich mir eine ganz neue Welt eröffnet: Ich konnte beispielsweise Datenanalysen und -visualisierungen für Datenjournalismus durchführen. Durch das Programmieren kann ich aktiv mit Softwareentwicklern zusammenarbeiten, um digitale Tools für die Arbeitsabläufe in der Redaktion zu entwickeln.

Die Handbücher und Dokumente, die ich in meinem vorherigen Job verfasst habe, sind leider nicht öffentlich zugänglich. Deshalb konzentriere ich mich jetzt darauf, mich mehr an Open-Source-Projekten zu beteiligen (siehe unten für Beispiele). Ich habe meine Arbeit im technischen Schreiben auf Stilhandbücher wie den Stilhandbuch für Entwicklerdokumentation von Google und den Stilhandbuch von Microsoft gestützt. Ich verwende regelmäßig GitHub, Slack und Linux. Ich habe mithilfe von Tools wie Sphinx, Mypy und Sphinx Autodoc Dokumentationen mit Erzählungen sowie Docstrings und Texthinweise verfasst.

Ich arbeite derzeit freiberuflich. Mein Zeitplan bietet mir die nötige Flexibilität, während der Entwicklungsphase der Dokumentation etwa 25 Stunden pro Woche an der Bokeh-Dokumentation zu arbeiten. Ich arbeite in der Pacific Time Zone, bin aber gerne bereit, mich an die Zeitpläne und Anforderungen des Teams anzupassen.

7. Aktuelle Beispiele für Open-Source-Dokumentation

  • PyZillow: PyZillow ist ein Python-Wrapper für die API der Immobilienwebsite Zillow.com. Zusätzlich zu einem Code und einer Rolle für die Codeverwaltung habe ich die vollständige Dokumentation verfasst. Ich habe Sphinx sowohl für die Dokumentation der Geschichte als auch für die Modulreferenz verwendet. Ich habe die Modulreferenz mit der Sphinx-Erweiterung „autodoc“ erstellt, basierend auf den Docstrings, die ich dem Code hinzugefügt habe.

  • PyPresseportal: PyPresseportal ist ein Python-Wrapper für die API der Website presseportal.de. Die Website presseportal.de ist einer der größten Distributoren von Pressemitteilungen und Investor Relations-Mitteilungen in Deutschland. Beispielsweise nutzen fast alle Polizei- und Feuerwehren diesen Dienst, um ihre Pressemitteilungen zu verbreiten. Nachdem ich die API viele Jahre als Journalist verwendet hatte, beschloss ich, eine Python-Schnittstelle zu entwickeln, um als Python-Objekte auf die umfangreichen Datenressourcen der Website zuzugreifen. Ich habe den Code und die gesamte Sphinx-basierte Dokumentation geschrieben.