Stackable

Der Stackable Docathon: Aufbau einer Datenpipeline

stackable-blog-header-blau

Letzten Monat haben wir unseren allerersten Dokumentations-Hackathon – oder „Docathon“ – bei Stackable durchgeführt. Das Ergebnis, das Du über den Link unten findest, ist ein Leitfaden für den Aufbaue einer einfachen Datenpipeline:

https://docs.stackable.tech/home/tutorials/end-to-end_data_pipeline_example.html

Wie jeder, der sich schon länger mit Software-Engineering beschäftigt, würden auch wir ohne zu zögern bestätigen, dass es fast unmöglich ist, seine Dokumentation wirklich konsequent aktuell zu halten. Es gibt natürlich teilweise Abhilfen und Strategien, wie z. B. die Aufnahme der Dokumentation in die „Definition of Done“ eines Scrum-Teams (was oft in „Documentation-less but Done“ ausartet), ein „Frühjahrsputz“ der Dokumentation vor einer Veröffentlichung, die Dokumentation so nah wie möglich am Code zu halten (z. B. Javadocs oder ähnliches;

Datenbank-Metadaten) oder sogar das Schreiben von Tests in die Dokumentation, wenn Rust es erlaubt. Aber es bleibt bei der Tatsache, dass diese Dokumentation normalerweise als lästige Pflicht angesehen wird.

In einer kürzlichen Team-Retrospektive haben wir beschlossen, einen internen Docathon zu veranstalten, um vor der demnächst anstehenden Veröffentlichung noch einige Lücken zu schließen. Als jemand, der noch nie an einem Hackathon – geschweige denn an einem Docathon – teilgenommen hat, hatte ich anfänglich Bedenken: Wie funktioniert das, wie funktioniert das remote und vor allem: wie funktioniert das, ohne langweilig zu werden? In diesem Beitrag fasse ich zusammen, was wir im Rahmen unseres Docathons gemacht haben, wie wir es gemacht haben und was wir dabei gelernt haben.

Was wir erreichen wollten

Uns gings es nicht darum, nur Inhalte für unsere Nutzer:innen bereitstellen, sondern auch unser eigenes Produkt auf Herz und Nieren prüfen, um Dinge zu erkennen, die wir bei der regulären Softwareentwicklung übersehen haben könnten. Gab es Probleme, die einem/einer Integrationstester:in verborgen geblieben sind, die aber für eine:n neue:n Benutzer:in nur allzu offensichtlich waren? Würden unsere Nutzer:innen nicht nur technisch, sondern auch intuitiv gut zusammenspielen? Wie gut kannten wir die Fähigkeiten der Datenprodukte, die von unseren Betreibern verwaltet werden?

Vor diesem Hintergrund und nach einer ersten Brainstorming-Sitzung beschlossen wir, eine User Journey zu dokumentieren, die folgende Punkte umfasst:

  • Abdeckung der Nutzung mehrerer unserer Operatoren in Kombination, anstatt nur die Lücken in den Beschreibungen der API-Aufrufe und dergleichen zu füllen
  • Bereitstellung eines detaillierten „How to“: vom Einrichten einer ersten Kubernetes-Umgebung bis hin zur Verarbeitung und Visualisierung eines mittelgroßen Datensatzes
  • Verwendung eines öffentlich zugänglichen Datensatzes für die Pipeline – genauer gesagt eines Teils der Taxidaten von New York City aus dem Jahr 2020
  • Bereitstellung einer Reihe detaillierter, wiederholbarer Schritte, die zu einem beispielhaften Dashboard führen, das das Ergebnis einer Datenaggregation anzeigt

Die endgültige Pipeline sieht wie folgt aus:

  • S3/Nifi: Einlesen von Daten aus einem öffentlichen externen S3-Bucket in Nifi
  • Nifi/Kafka: eine beispielhafte einfache Datentransformation
  • Kafka/Druid: Definition eines Ingestion-Jobs in Druid, der diese Daten aus dem gleichen Kafka-Topic wie im vorherigen Schritt liest und eine Druid-Datenquelle erstellt
  • Druid/Superset: Referenzierung dieser Datenquelle in Superset und Verwendung zur Erstellung eines Diagramms auf einem Dashboard

Die Pipeline umfasst insgesamt 5 Operatoren:

Nifi-Kafka-Druid-Superset-Operatoren in Kombination für die Datenverarbeitung, plus Zookeeper (verwendet für die Sicherung der Konfigurationsspeicherung durch Kafka und Nifi). Weitere Einzelheiten finden Sie in der Anleitung, auf die in diesem Artikel verwiesen wird.

Was wir gemacht haben

In einem ersten Schritt haben wir einige Grundregeln festgelegt.

Was soll dokumentiert werden?

Wir einigten uns darauf, nicht zu viel zu dokumentieren, d. h. keine Dinge, die wir noch nicht implementiert hatten! Denn wir wollten die User Journey in ihrer Gesamtheit beschreiben – auch wenn das bedeutete, etwas zu „optimistisch“ zu sein. Wir haben jedoch schnell einen pragmatischen Ansatz gewählt: Da wir wollten, dass unser endgültiges Artefakt etwas ist, das unsere Nutzer:innen mitnehmen und ausprobieren können, statt es nur als Theorie durchzulesen, haben wir für alle fehlenden oder unvollständigen Elemente Themen eröffnet, die wir innerhalb von ein oder zwei Tagen implementieren konnten, wenn wir auf sie stießen. So wurden wir – solange es sich nicht um neue Funktionen handelte – nicht durch Dinge aufgehalten, die wir übersehen hatten.

Wie soll man dokumentieren?

Nach einer kurzen Diskussion über all die wunderbaren Formatierungstools, die es in der Welt des Internets gibt, haben wir beschlossen, dem Inhalt Vorrang vor dem Format zu geben: lieber eine Menge Material auf (virtuelles) Papier bringen und später die Feinabstimmung vornehmen, als einen erheblichen Aufwand für die Formatierung während des Docathons zu betreiben. Ein einziges gemeinsames Online-Dokument mit eingefügten Screenshots war für unsere Bedürfnisse ausreichend.

Dauer, Gruppen und Untergliederungen

Auch hier wollten wir die Dinge leicht und pragmatisch halten: Wir sind ein Team, das über drei Länder in zwei Zeitzonen verteilt ist, also haben wir die Übung auf zwei Tage mit jeweils einem Zeitfenster von 09.00-15.00 verteilt. Jeder Tag begann mit einem kurzen (halbstündigen) Auftakt/Rückblick. Am ersten Tag gab es eine Mittagsrunde, am zweiten Tag beendeten wir die Übung mit einer kurzen Nachbereitung am Ende des Arbeitstages. Zu allen anderen Zeiten arbeiteten wir in drei Gruppen von etwa 3 – 4 Personen und mit Ad-hoc-Slack-Chats zwischen den Teams, um Überschneidungen, Schnittstellen und andere Fragen zu klären.

Nachbereitung der Arbeit

Die Formatierung und Konsolidierung der Beiträge der einzelnen Teams nahm etwas Zeit in Anspruch, aber das lag zum Teil daran, dass wir sehr viele Inhalte hatten, mit denen wir arbeiten mussten! Da es effizienter war, das Dokument als Ganzes zu formatieren und zu überprüfen, als zu versuchen, dies durch parallele Arbeit zu erreichen, haben wir diese Aufgabe nur einem Teil des Teams zugewiesen. Nur wenige Tage später hatten wir ein konsolidiertes Dokument, das nach Überprüfungen und kleinen Verbesserungen etwa sieben bis zehn Tage später online ging.

Was wir nicht gemacht haben

Um die Dinge so einfach wie möglich zu halten, haben wir absichtlich z. T auf Authentifizierung und Autorisierung verzichtet . Um die Wartezeiten während der Validierungstests so gering wie möglich zu halten, haben wir zudem den Zieldatensatz so gewählt, dass er eine überschaubare Größe hat.

Lessons Learned

Unsere Erkenntnisse und Tipps, die wir für das nächste Mal beachten werden, möchte ich kurz zusammenfassen:

  • Einigt Euch auf exakte Schnittstellendefinitionen – z. B. präzise Definition des Datensatzes, Name des Kafka-Topics – bevor Ihr startet. Bis zur Konsolidierungsphase war uns nicht klar, dass wir tatsächlich zwei verschiedene Monate aus den NYC-Taxidaten ohne gemeinsame Schnittmenge verwendet hatten sodass das endgültige Dashboard zunächst leer war!
  • Haltet die Dokumentation der noch nicht implementierten Funktionen auf einem überschaubaren Niveau (z. B. Dinge, die im Laufe des Docathons oder kurz nach dessen Abschluss implementiert werden können)
  • Akzeptiere, dass Ihr wahrscheinlich überschätzen werdet, was Ihr in den ersten vier Stunden erreichen könnt – aber unterschätzt nicht, was in zwei Tagen erreicht werden kann.
  • Beschränkt Dokumentationsrichtlinien und -konventionen auf ein absolutes Minimum: Inhalt geht vor Präsentation! Es ist effizienter, alles zusammenzufassen und zu formatieren, wenn man mit einfachem Text arbeitet.
  • Führt eine Release aller Komponenten durch, bevor der Docathon beginnt, sodass Ihr Komponenten dokumentiert, die sich in einem stabilen Zustand befinden.
  • „Eat your own dogfood“: Seid Euch bewusst, dass wir unser eigenes Produkt nutzen müssen, um effizient und effektiv etwas über unser Projekt zu lernen. Diese Übung hat uns geholfen, die Produkte selbst sowie unsere eigenen Anwender:innen besser zu verstehen und hat uns eine Vorlage für die Benutzerführung geliefert, die für ähnliche Szenarien in der Zukunft angepasst werden kann. Sie zeigt auch Aspekte der Interoperabilität auf, die sich von denen unterscheiden, die durch Integrationstests abgedeckt werden.
  • Fokussiert Euch auf eine überschaubare Teamgröße. Wenn die Gruppen klein bleiben – z. B. drei bis fünf Personen – bleibt man flexibel, pragmatisch und engagiert.

Fazit

Ich bin mir sicher, dass wir diese Übung bei Stackable wiederholen werden: Ja, Dokumentation kann tatsächlich Spaß (!) machen – vor allem, wenn man sie aus der Perspektive des/der Nutzer:in betrachtet und mit dem Ziel, für diese ein bestimmtes Tutorial als Endergebnis zu erstellen.

Verwandte Links:

https://www1.nyc.gov/site/tlc/about/tlc-trip-record-data.page https://s3.amazonaws.com/nyc-tlc/trip+data/yellow_tripdata_2020-05.csv https://docs.stackable.tech/home/tutorials/end-to-end_data_pipeline_exampl e.html

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Copy link
Powered by Social Snap