Bei Dagster Labs erstellen wir viele technische Lernmaterialien für Fachleute aus den Bereichen Data Engineering, Machine Learning Engineering und Datenanalyse. Darin erklären wir, wie sie Dagster nutzen können, unser Open-Source-Framework zur Orchestrierung von Workflows. Wer Dagster nutzt, bringt ganz unterschiedliche technische Vorkenntnisse mit. Deshalb ist es für uns wichtig, für jede Zielgruppe die richtige Detailtiefe zu finden.
In diesem Beitrag zeige ich, wie wir mit Codex von OpenAI schneller dokumentieren, Inhalte für verschiedene Medien aufbereiten und sogar messen, wie vollständig unsere Dokumentation ist.
Was eine gute CONTRIBUTING.md bewirkt
Wir haben unsere Datei CONTRIBUTING.md überarbeitet, damit Mitglieder der Community und unser Entwicklungsteam leichter zur Dokumentation beitragen können. Ein Nebeneffekt hat uns überrascht: Auch Codex konnte uns dadurch deutlich besser unterstützen. Es lohnt sich, direkt in der Codebasis festzuhalten, wie die Dokumentation gegliedert ist, wie die einzelnen Ebenen zusammenhängen und was sich beim Schreiben bewährt hat. Davon profitieren Menschen ebenso wie Maschinen.
# Contributing documentation
## Content
### Links
#### Use full paths instead of relative links
Docusaurus doesn't always render relative links correctly, which can result in users seeing intermittent 404s when accessing those links. Use full paths instead of relative links, like this:
```
For more information, see "[Defining assets](/guides/build/assets/defining-assets)".
```
instead of this:
```
For more information, see "[Defining assets](defining-assets)".
```
#### Use non-trailing slash links to Dagster docs
e.g. use `/guides/build/assets/defining-assets` instead of `/guides/build/assets/defining-assets/`.
**Context:** Links to Dagster docs with trailing slashes automatically redirect to non-trailing slash links. While that's helpful for docs links we don't control, too many redirects on our own pages can confuse search engines and cause SEO issues.
### API documentation
...
Wie gut Codex arbeitet, hängt davon ab, welche Orientierung du ihm gibst. Eine klar gegliederte CONTRIBUTING.md dient Menschen als Anleitung und der KI als Wegweiser.
Mit Codex Code verstehen
Codex hilft uns auch jenseits der Dokumentation: Wir können uns jederzeit Code erklären lassen. Für unsere Teams in Developer Advocacy und technischer Redaktion ist das besonders wertvoll. In Open-Source-Projekten oder Projekten mit großen Entwicklungsteams ist es oft schwierig, den Überblick zu behalten: Welche Funktionen entstehen gerade und wie funktionieren sie? Für kleine Teams in Developer Advocacy und technischer Redaktion gilt das umso mehr. Besonders hilfreich ist Codex für uns, wenn wir uns einen Pull Request erklären lassen oder auf einen bestimmten Teil der Codebasis verweisen und fragen, wie er funktioniert.
Ein Tipp aus unserer Praxis: Lass Codex den Befehl gh nutzen, um dir einen Pull Request zu erklären. Bitte Codex, die Beschreibung und den Diff zu prüfen, den Grund für die neue Funktion zusammenzufassen und zu erläutern, wie du sie den Menschen zugänglich machen solltest, die das Produkt nutzen.
Die Vorteile eines Monorepos
Darüber lässt sich streiten, aber ich bin ein großer Fan von Monorepos. Wenn es auf den Kontext ankommt, finde ich das, was ich brauche, viel leichter in einem einzigen Repository. Für Codex bedeutet das, dass der gesamte Kontext an einem Ort verfügbar ist: Code, Dokumentation und Beispiele.
Manche bezweifeln, dass Werkzeuge wie Codex auch mit wachsenden Repositorys zurechtkommen. Diese Erfahrung habe ich nicht gemacht. Über Dateiverweise (@) kannst du Codex ein Unterverzeichnis oder eine Datei als Ausgangspunkt für die weitere Suche nennen. Es hat auch handfeste Vorteile, den Framework-Code und die Dokumentation im selben Repository zu pflegen. So können wir Codex bitten, den Code zu lesen und daraus einen ersten Entwurf für die Dokumentation zu erstellen, den wir anschließend ausarbeiten.
Im folgenden Beispiel haben wir Codex gebeten, einen bestehenden Pull Request zu prüfen und die Dokumentation um einen Abschnitt zu ergänzen. Er sollte genau erklären, wie sich die betreffenden Umgebungsvariablen bei der Konfiguration eines Deployments nutzen lassen.
>_ You are using OpenAI Codex in ~/src/dagster
To get started, describe a task or try one of these commands:
/init - create an AGENTS.md file with instructions for Codex
/status - show current session configuration and token usage
/approvals - choose what Codex can do without approval
/model - choose what model and reasoning effort to use
▌ Prüfe mit `gh pr diff <number>` die Änderungen in Pull Request 32557. Prüfe, welche Umgebungsvariablen
▌ zur Konfiguration des gRPC-Servers hinzugekommen sind und welche es bereits gab. Beschreibe anschließend
▌ die Konfigurationsmöglichkeiten auf der Seite docs/docs/deployment/oss/oss-instance-configuration.md.
> I’ll fetch the diff for PR 32557 and scan for added/updated gRPC-related
environment variables, then cross-check with existing env var usage in the
repo.
• Ran gh pr diff 32557 | sed -n '1,200p'
• Ran gh pr diff 32557 | sed -n '200,400p'
• Explored
└ Search DAGSTER_GRPC_[A-Z_]+ in dagster
Read api.py, code_server.py, oss-instance-configuration.md
Search DAGSTER_CODE_SERVER_[A-Z_]+
Read constants.py
Search DAGSTER_(REPOSITORY|SCHEDULE|SENSOR)_GRPC_TIMEOUT_SECONDS|
DAGSTER_GRPC_SHUTDOWN_GRACE_PERIOD in dagster
Read proxy_server_manager.py
> Next, I’ll expand the gRPC servers section of the instance configuration docs
to include API gRPC server variables and communication timeouts/limits, keeping
style consisten
...
Den Pull Request aus dieser Sitzung findest du hier: dagster-io/dagster # 32558.
Inhalte für verschiedene Lernformate aufbereiten
Verschiedene Zielgruppen bevorzugen unterschiedliche Lernformate, obwohl sie sich oft mit denselben Fragen beschäftigen. Deshalb erstellen wir Blogbeiträge, Tutorials, Onlinekurse, YouTube-Videos und mehr. Häufig vermitteln wir dabei dieselben Inhalte. Je nach Zielgruppe bereiten wir sie anders auf.
Codex kann Inhalte besonders gut von einem Format ins andere übertragen. Aus einem Tutorial kann Codex zum Beispiel ein Skript für ein YouTube-Video erstellen. Für einen Blogbeitrag kann es ein technisch detailliertes Tutorial auf einer etwas allgemeineren Ebene erklären. Der folgende Ausschnitt zeigt den Prompt, mit dem wir aus einem unserer Beispielprojekte ein Videoskript erstellt haben. Das spart uns Stunden beim Umschreiben, und unsere Aussagen bleiben über alle Kanäle hinweg konsistent.
>_ You are using OpenAI Codex in ~/src/dagster
▌Sieh dir das Beispielprojekt examples/docs_projects/project_dagster_modal_pipes an.
▌Erstelle ein Videoskript, das dem Publikum das zentrale Konzept von Dagster und Modal
▌anhand dieses Beispiels erklärt. Gliedere das Skript in Abschnitte und füge Codeausschnitte ein,
▌die im Video gezeigt werden sollen. Schreib den Sprechertext unterhaltsam und professionell.
▌Speichere das Skript in MODAL_VIDEO_TRANSCRIPT.md.
> I’m going to scan the example project to understand its structure and code
before drafting the video transcript.
• Ran
└ bash -lc 'ls -la' bash -lc 'ls -la examples/docs_projects/
project_dagster_modal_pipes' bash -lc "rg --files examples/docs_projects/
project_dagster_modal_pipes | sed -n '1,120p'"
• Explored
└ List project_dagster_modal_pipes
Search rg --files examples/docs_projects/project_dagster_modal_pipes
Read README.md, definitions.py, __init__.py, resources.py, constants.py,
feeds.py, pipeline_factory.py, summarize.py, config.py, transcribe.py,
hello_dagster.py, verify_cloud_mount.py
• Added MODAL_VIDEO_TRANSCRIPT.md (+335 -0)
Das vollständige Videoskript findest du hier!
Prüfen, was die Dokumentation abdeckt
Wir experimentieren auch damit, anhand der Ergebnisse von Codex einzuschätzen, wie gut Menschen unsere Dokumentation verstehen können.
Dazu geben wir Codex unsere Dokumentation als maßgebliche Quelle und Ausgangspunkt vor und lassen es auf dieser Grundlage Code generieren. Ein häufiger Anwendungsfall für Dagster ist zum Beispiel, dbt-Datenmodelle zusammen mit anderem Code zur Datenverarbeitung auszuführen und zu überwachen.
Wir bitten Codex, anhand der Dokumentation den Code für ein solches Projekt zu erstellen. Anschließend prüfen wir mit einer Testsuite, ob der Code wie erwartet funktioniert. Besteht er die Tests, können wir davon ausgehen, dass unsere Dokumentation die dafür nötigen Inhalte ausreichend abdeckt. Wenn Codex allein anhand unserer Dokumentation funktionierenden Code erstellen kann, spricht viel dafür, dass Menschen das ebenfalls können. So erhalten wir einen indirekten Maßstab für die Vollständigkeit unserer Dokumentation.
Fazit
Codex hilft uns im Dagster-Team enorm dabei, Lerninhalte zu erstellen, zu prüfen und in andere Formate zu übertragen. Wir können heute mehr Material erstellen als früher und besser sicherstellen, dass unsere Dokumentation auch bei der Weiterentwicklung des Frameworks die nötigen Themen abdeckt. Vor allem fällt es uns leichter, unsere Community zu unterstützen.
Die Arbeit mit Codex hat uns gezeigt, wie wichtig Kontext und Struktur sind. Deshalb verbessern wir den Aufbau unserer Dokumentation, damit sich Menschen und KI darin gut zurechtfinden. Die Rückmeldungen aus der Arbeit mit KI helfen uns, bessere Inhalte zu erstellen. Davon profitieren wiederum alle, die anhand unserer Dokumentation Code für das Framework generieren. Mit der Weiterentwicklung von KI-Werkzeugen werden die Grenzen zwischen Dokumentation, Code und Automatisierung fließender. Teams, die Dokumentation als strukturierte Daten behandeln, werden dabei einen großen Vorteil haben.