Bokeh-Projekt

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

Projektbeschreibung

Erstellen, lesen, teilen: Dokumentation von Bokeh optimieren

1. Zusammenfassung

Bokeh ist ein äußerst leistungsfähiges Tool zum Erstellen interaktiver, browserbasierter Visualisierungen mit Python. Sie hat eine beträchtliche Nutzerbasis (502.000 Conda-Downloads pro Monat, 855.000 PyPi-Downloads) und eine große Anzahl von Mitwirkenden (455 Beitragende auf GitHub). Es überrascht nicht, dass die umfangreiche Dokumentation von Bokeh organisch gewachsen ist. Daher sind sie manchmal uneinheitlich, schwer zugänglich und verwickelt.

Die „Season of Docs“ von Google bietet eine einzigartige Gelegenheit für eine gezielte Überprüfung und Überarbeitung der Struktur und des Inhalts der Bokeh-Dokumentation – 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 jedoch zu einem einzigartigen Teilnehmer der „Season of Docs“ von Google macht, ist mein Journalismus: Ich habe über 13 Jahre lang in der Redaktion gearbeitet, und viele Jahre als leitender Redakteur und Verfechter des digitalen Wandels. Neben meinen journalistischen Aufgaben musste ich immer mehr Verantwortung für die Entwicklung und Dokumentation neuer digitaler Tools und Styleguides übernehmen sowie Mitarbeiter in der Redaktion schulen.

Nach meinem kürzlichen Umzug von Europa in die USA beschloss ich, neue Wege zu finden, um meine Begeisterung für Kommunikation und Programmieren unterzubringen. Für mich ist das technische Schreiben die optimale Kombination aus meinen Fähigkeiten und Erfahrungen in den Bereichen Schreiben und Technik. In diesem Vorschlag werde ich darlegen, wie ich die Google-Dokumente für die Saison nutzen werde, um die Bokeh-Dokumentation zu optimieren. Das Erstellen und die Unterstützung von Dokumentationen wird vereinfacht, das Lesen der Dokumentation vereinfacht und das Teilen der Dokumentation mit anderen vereinfacht.

2. Aktuelle Situation

Die offizielle Dokumentation von Bokeh besteht aus folgenden Haupteinheiten:

  • Beschreibende Dokumentation: Installationsanleitung, Nutzerhandbuch, Entwicklerhandbuch, Versionshinweise
  • Galerie und Demos (interaktive Beispiele mit Quellcode)
  • Referenzhandbuch (Dokumentation basierend auf docstrings)
  • Anleitung (umfangreiche Sammlung von Jupyter Notebooks, gehostet auf mybinder.org)
  • Hilfe zu Docstrings und Modellen für IDEs
  • Beispiele und README-Dateien im Projekt-Repository

Darüber hinaus finden Sie im Bokeh-Supportforum und auf Stack Overflow, wo der Entwickler von Bokeh aktiv Antworten auf Nutzerfragen gibt, sowie im Medium-Blog von Bokeh eine Fülle von Informationen.

Die meisten Dokumentationswebseiten werden mit Sphinx mit mehreren Standard- und benutzerdefinierten Sphinx-Erweiterungen erstellt. Das Referenzhandbuch wird beispielsweise aus docstrings mithilfe von Erweiterungen wie „autodoc“ und dem benutzerdefinierten „bokeh_autodoc“ generiert. Wie bei organisch gewachsenen Dokumentationen enthält sie Redundanzen und Inkonsistenzen.

Eines der ersten Dinge, die mir bei der Analyse der vorhandenen Dokumentation aufgefallen sind, war das Fehlen klarer Stilrichtlinien für das Verfassen von Dokumentationen. Der Bokeh-Entwicklerleitfaden enthält einige grundlegende Anleitungen. Dieses Dokument enthält jedoch nicht viele Hinweise zum Stil, insbesondere zu Dokumentationen, die über docstrings hinausgehen. Infolgedessen erschweren stilistische und strukturelle Probleme den Zugriff auf die Informationen in den Dokumenten, insbesondere für Neuankömmlinge.

Beispiel:

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

3. Tore

Um die elfwöchige Dokumententwicklungsphase am effizientesten nutzen zu können, werde ich mich auf drei Schlüsselelemente konzentrieren:

3.1. Erstellen der Dokumente verbessern

Der Großteil der Dokumentation von Bokeh stammt von Mitwirkenden, die sie in Pull-Anfragen für neue Funktionen und Fehlerkorrekturen einbeziehen. Obwohl ich einen Teil der Dokumententwicklungsphase nutzen werde, um die vorhandenen Dokumente zu bearbeiten und zu refaktorieren, werde ich betonen, dass die Workflows zum Erstellen und Pflegen der Dokumentation zukunftssicher sind: Es sollte für Beitragende so einfach wie möglich sein, einen gleichbleibend hohen Dokumentationsstandard aufrechtzuerhalten.

Ich werde dies mit zwei Ansätzen sicherstellen:

  • Ich werde eine Reihe praktischer, einfacher Stilrichtlinien erstellen, die in den bestehenden Entwicklerleitfaden aufgenommen werden. In diesen Richtlinien geht es um Stil, Grammatik und Struktur. Darüber hinaus werde ich interne Kommunikationskanäle wie Slack verwenden, um sicherzustellen, dass die Beitragenden von Bokeh mit den Stilrichtlinien vertraut sind. Außerdem biete ich Einzelschulungen sowie Fragerunden für das Team an.
  • Ich werde mit dem Kernteam zusammenarbeiten, um optimale Tools für die Qualitätskontrolle der Dokumentation zu finden, die zu den bestehenden Workflows von Bokeh für PRs (Pull-Anfragen) und CI (Continuous Integration) hinzugefügt werden. Je nach Anforderungen des Teams könnte dies bedeuten, dass Tools wie die Rechtschreibprüfung pydocstyle, proselint oder sphinxcontrib-spelling zur Testsuite von Bokeh, die Pre-Commit-Einrichtung oder GitHub-Aktionen hinzugefügt werden. Ich habe den GitHub-Aktionen eines meiner eigenen Open-Source-Projekte ein funktionierendes Proof of Concept hinzugefügt.

3.2. Das Lesen der Dokumente verbessern

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

Schlüsselfaktoren für die Gebrauchstauglichkeit eines Textes sind sein Stil und die Struktur: Wenn die Dokumentation in einem klaren, einheitlichen Stil verfasst wird, können die Lesenden Informationen schnell aufnehmen, ohne Ablenkungen und überflüssige Sprache. Eine geradlinige und transparente Struktur der Dokumentation erleichtert das schnelle Auffinden relevanter Informationen.

Ich werde mich auf diese beiden Bereiche konzentrieren, wobei der Schwerpunkt auf der Usability für neue Nutzende liegt. Dazu gehört auch eine gründliche Durchsicht der Dokumentation, die sich auf das Nutzerhandbuch konzentriert. Außerdem werde ich die Landingpage der Dokumentation überarbeiten, um unterschiedliche Zielgruppen besser anzusprechen und dafür zu sorgen, dass jeder Nutzer schnell die richtigen Ressourcen findet.

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

3.3. Freigabe der Dokumente verbessern

Immer mehr Diskussionen über Bokeh erfolgen auf Plattformen von Drittanbietern. Viele dieser Plattformen verwenden Metadaten wie OpenGraph von Facebook, um umfassende Links in der Vorschau anzuzeigen. OpenGraph wird von Diensten wie Facebook, Twitter, LinkedIn, Slack und iMessage verwendet. Das Discourse-Forum von Bokeh verwendet OpenGraph auch zum Rendern von Linkvorschauen.

Um diese Technologie nutzen zu können, werde ich Metadaten zu den Sphinx-generierten Webseiten von Bokeh hinzufügen, wie in Ausgabe 9792 beschrieben. Die effizienteste Methode 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 Dokumententwicklungsphase nutzen, um diese Erweiterung für die Verwendung mit der Dokumentation von Bokeh zu verbessern.

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

Ein nächster Schritt bei der Entwicklung dieser Erweiterung wäre die Einführung benutzerdefinierter Anweisungen zur manuellen Definition von OpenGraph-Metadaten (ähnlich zu den bestehenden 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 wesentlich komplexer, daher werde ich mich primär auf das Einfügen hochwertiger OpenGraph-Metadaten für die Bokeh-Dokumentation konzentrieren. Mit der gesamten Arbeit für die Unterstützung von OpenGraph legen Sie gleichzeitig den Grundstein 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 zum Beispiel bei den Problemen #1758 und #5208 zum Ausdruck gebracht. Ich werde darauf achten, eng mit ihnen zusammenzuarbeiten.

4. Ergebnisse

Zusammenfassend sind die Ergebnisse aus Season of Docs zu erwarten:

  • Richtlinien für den Dokumentationsstil für Bokeh-Beitragende
  • PR- und CI-Workflows wurden überarbeitet, um automatisierte Qualitätskontrollen für die Dokumentation zu ermöglichen.
  • Bearbeitetes und umstrukturiertes Nutzerhandbuch
  • Überarbeitete Dokumentations-Landingpage
  • OpenGraph-Metadaten, die in den Dokumentationswebseiten enthalten sind, und eine funktionierende Sphinx-Erweiterung

Zusätzlich werde ich ein „Doclog“ speichern, um meine Reise durch Googles „Season of Docs“ auf meiner persönlichen Website/Medium oder auf dem Medium-Blog von Bokeh zu dokumentieren. Diese dient auch als Grundlage für den Projektbericht für Google. Ich werde nach Möglichkeit alles transparent in Form von GitHub-Problemen und Pull-Anfragen tun.

5. Zeitplan

Vor der Phase der Community-Beziehung: Ich nehme bereits 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 mich aktiv an der Diskussion über Bokeh beteiligen und mich außerdem mit Bokeh vertraut machen, indem ich Visualisierungen erstelle und veröffentliche.

Aufbau der Community (17.08.–13.09.):

  • Das Kernteam kennenlernen, den Projektplan im Austausch mit den beratenden Personen optimieren
  • Einen Zeitplan und Kommunikationskanäle für regelmäßige Berichterstattung und Feedback mit den beratenden Personen einrichten
  • Seien Sie auf Slack bei Bokeh aktiv, um alle interessierten Bokeh-Mitwirkenden über die Google Docs-Saison und die Ziele der Dokumententwicklungsphase zu informieren.
  • Feedback von Bokeh-Mitwirkenden einholen, um den Plan für die Dokumententwicklungsphase weiter zu verfeinern

Entwicklungsphase des Dokuments

Woche 1, 14.09.–20.09.:

  • Mit dem Prüfen und Bearbeiten der Narrativdokumentation beginnen
  • Mit der Ausarbeitung von Stilrichtlinien beginnen

Woche 2, 21.09.–27.09.:

  • Weiter an Stilrichtlinien arbeiten
  • Erzählungsdokumentation weiter bearbeiten
  • Mit der Überarbeitung der Landingpage der Dokumentation beginnen

Woche 3, 28.09.–04.10.:

  • Stilrichtlinien fertigstellen
  • Landingpage für die Dokumentation fertigstellen

Woche 4, 05.10.–11.10.:

  • Bearbeitung der Dokumentation abschließen
  • Mit dem Bokeh-Kernteam über die Integration von Tools für die Qualitätskontrolle von Dokumenten in PR/CI-Workflows sprechen

Woche 5, 12.10.–18.10.:

  • Fragen und Antworten mit Bokeh-Mitwirkenden auf Slack vereinbaren, um Stilrichtlinien, Verbesserungen der Narrativdokumentation und PR/CI-Workflows zu besprechen
  • Mit der Entwicklung meines vorhandenen Proof of Concept für OpenGraph-Metadaten in eine bereitstellbare Sphinx-Erweiterung beginnen
  • Stilrichtlinien basierend auf dem Feedback aus den Fragerunden mit Bokeh-Beitragenden überarbeiten

Woche 6, 19.10.–25.10.:

  • Mit dem Testen von Tools zur Qualitätskontrolle von Dokumenten in PR- und CI-Workflows beginnen
  • Weiterentwicklung der Sphinx-Erweiterung für Metadaten

Woche 7, 26.10.–01.11.:

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

Woche 8, 02.11.–08.11.:

  • Die Sphinx-Erweiterung bereitstellen und eine Landingpage mit verbesserter Dokumentation und Dokumentation veröffentlichen

Woche 9, 09.11.–15.11.:

  • Tools zur Qualitätskontrolle für Dokumente in PR- und CI-Workflows bereitstellen
  • Entwicklerleitfaden aktualisieren und veröffentlichen, um Stilrichtlinien sowie Ergänzungen des PR- und CI-Workflows hinzuzufügen

Woche 10, 16.11.–22.11.:

  • Verbleibende Aufgaben abschließen

Woche 11, 23.11.–29.11.:

  • Mit dem Schreiben eines Projektberichts beginnen
  • Mit dem Schreiben der Projektbewertung beginnen

Projektabschlussphase

Woche 12, 30.11.–05.12:

  • Projektbericht abschließen und einreichen

Woche 13, 03.12.–10.12.:

  • Projektbewertung abschließen und einreichen

Nach Abschluss der Season of Docs bei Google:

  • Ich hoffe, weiterhin an der Entwicklung von Bokeh beteiligt zu sein und weiter an der Dokumentation von Bokeh zu arbeiten.
  • Ich habe vor, die Entwicklung einer Sphinx-Erweiterung für OpenGraph-/Structured Data-Metadaten fortzusetzen.
  • Ich möchte meinen Hintergrund im Journalismus und mein bestehendes Netzwerk nutzen, um Bokeh als Tool im Datenjournalismus zu bewerben. Sie haben beispielsweise vor einem journalistischen Publikum über Bokeh geschrieben oder Konferenzvorträge über die Verwendung von Bokeh im journalistischen Kontext angeboten.

6. Über mich

Ursprünglich bin ich Journalistin und habe früher Erfahrung im Fernsehen, im Internet und im Radio. Als leitender Redakteur und Reporter im Bereich Fernsehen und digitale Nachrichten habe ich jahrelange Erfahrung beim Schreiben und Bearbeiten von Nachrichten gesammelt. Gleichzeitig habe ich an mehreren Projekten zur digitalen Transformation und Automatisierung gearbeitet. Ich habe zahlreiche Handbücher zu digitalen Tools und Workflows sowie Styleguides und Kommunikationsstrategien für digitale Nachrichtenunternehmen verfasst. Außerdem habe ich Teammitglieder in der Verwendung dieser Tools geschult.

Ich war schon immer an den Schnittpunkten zwischen Kommunikation und Technologie interessiert. Als ich das Programmieren in Python lernte, öffnete sich eine ganz neue Welt: Ich war beispielsweise in der Lage, Datenanalysen und Visualisierungen für Datenjournalismus durchzuführen. Da ich Programmieren gelernt habe, konnte ich aktiv mit Softwareentwicklern zusammenarbeiten, um digitale Tools für die Arbeitsabläufe in den Redaktionen zu entwickeln.

Die Handbücher und Dokumente, die ich bei meiner vorherigen Tätigkeit verfasst habe, sind leider nicht öffentlich. Daher konzentriere ich mich jetzt darauf, mich stärker in Open-Source-Projekte zu engagieren (siehe Beispiele unten). Meine Arbeit im technischen Bereich basiert auf Styleguides wie den Styleguides für Entwickler von Google und den Styleguides von Microsoft. Ich verwende regelmäßig GitHub, Slack und Linux. Ich habe Narrativdokumentationen sowie Docstrings und Typhinweise mit Tools wie Sphinx, Mypy und Sphinx Autodoc geschrieben.

Ich bin derzeit freiberuflich tätig. Mein Zeitplan bietet die nötige Flexibilität, um während der Entwicklungsphase etwa 25 Stunden pro Woche an der Dokumentation von Bokeh zu arbeiten. Ich arbeite in der pazifischen Zeitzone, bin aber gerne bereit, die Zeitpläne und Anforderungen des Teams zu berücksichtigen.

7. Aktuelle Beispiele aus der Open-Source-Dokumentation

  • PyZillow: PyZillow ist ein Python-Wrapper für die API der Immobilienwebsite Zillow.com. Neben der Bereitstellung von Code und als einer der Code-Verwalter habe ich auch die vollständige Dokumentation verfasst. Ich habe Sphinx sowohl für die Erzählungsdokumentation 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 Vertreiber von Pressemitteilungen und Investor-Relation-Ankündigungen in Deutschland. Fast alle Polizei- und Feuerwehren nutzen diesen Dienst beispielsweise für die Veröffentlichung von Pressemitteilungen. Nachdem ich die API viele Jahre als Journalistin genutzt hatte, beschloss ich, eine Python-Schnittstelle zu entwickeln, um auf die umfangreichen Datenressourcen der Website als Python-Objekte zuzugreifen. Ich habe den Code und die gesamte Sphinx-basierte Dokumentation geschrieben.