Chez Dagster Labs, nous produisons de nombreux contenus pédagogiques techniques pour aider les ingénieurs data, les ingénieurs en machine learning et les analystes à mieux comprendre comment utiliser Dagster, un framework open source d’orchestration de workflows. Nos utilisateurs ayant des parcours techniques variés, nous avons constaté qu’il était essentiel d’adapter le niveau de détail technique à chaque profil.
Dans cet article, je vous explique comment nous utilisons Codex d’OpenAI pour accélérer la rédaction de documentation, adapter les contenus à différents supports et même mesurer à quel point notre documentation est complète.
Les atouts des fichiers CONTRIBUTING.md
Pour permettre aux membres de notre communauté et à nos ingénieurs de contribuer plus facilement à la documentation, nous avons remanié notre fichier CONTRIBUTING.md. À notre surprise, nous avions aussi, sans le vouloir, rendu Codex nettement plus utile. Décrire clairement la hiérarchie, la structure et les bonnes pratiques de rédaction de la documentation au sein du code source s’avère très précieux. Pour les humains comme pour les robots.
# 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
...L’efficacité de Codex dépend du cadre que vous lui fournissez. Un fichier CONTRIBUTING.md bien structuré sert à la fois de documentation pour les humains et de guide pour l’IA.
Mieux comprendre le code avec Codex
Au-delà de la rédaction de documentation, Codex peut expliquer le code à tout moment. Cette aide s’est révélée précieuse pour les équipes de relations développeurs et de rédaction technique. Dans les projets open source ou ceux qui mobilisent de nombreux ingénieurs, il est souvent difficile de suivre toutes les fonctionnalités en cours de développement et leur fonctionnement. C’est particulièrement vrai lorsque les équipes de relations développeurs et de rédaction technique sont petites. Nous avons constaté que Codex nous apporte une aide particulièrement utile lorsque nous lui demandons d’expliquer des pull requests ou une partie du code source que nous lui indiquons.
Une astuce que nous avons découverte consiste à utiliser la commande gh depuis Codex pour expliquer les pull requests. Demandez-lui d’examiner la description et le diff de la PR, de résumer pourquoi la fonctionnalité a été implémentée et d’expliquer comment elle devrait être présentée aux utilisateurs finaux.
Les atouts du monorepo
Cet avis ne fera peut-être pas l’unanimité, mais je suis un grand adepte des monorepos. Lorsque le contexte est essentiel, tout regrouper dans un seul dépôt facilite grandement l’accès aux éléments nécessaires. Pour Codex, cela signifie disposer d’un contexte complet : le code, la documentation et les exemples au même endroit.
Certains craignent que des outils comme Codex ne suivent pas lorsque les dépôts grossissent, mais ce n’est pas ce que j’ai constaté. Grâce aux références de fichiers dans Codex (@), vous pouvez lui indiquer un sous-répertoire ou un fichier comme point de départ avant qu’il poursuive son exploration. Regrouper le code du framework et la documentation dans un seul dépôt présente aussi de sérieux avantages. Cette organisation nous permet de demander à Codex de lire le code du framework et de rédiger des ébauches de documentation que nous pouvons ensuite affiner.
Voici un exemple dans lequel nous avons demandé à Codex d’examiner une pull request existante et d’ajouter à la documentation une section expliquant précisément l’utilité de ces variables d’environnement pour configurer votre déploiement.
>_ 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
▌ Review the changes made in pull request 32557 using `gh pr diff <number>`, review the environment
▌ variables that were introduced and already exist for configuring the gRPC server, then update
▌ docs/docs/deployment/oss/oss-instance-configuration.md page to outline the configuration options.
> 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
...Vous pouvez consulter la pull request produite lors de cette session ici : dagster-io/dagster # 32558.
Adapter les contenus à différents supports
Chaque profil a ses préférences en matière de formats d’apprentissage, mais les idées de fond sont souvent les mêmes. C’est pourquoi nous produisons des contenus sur différents supports : articles de blog, tutoriels, cours en ligne, vidéos YouTube, etc. Le fond peut souvent rester le même, seule la présentation change selon le public visé.
Codex excelle dans l’adaptation des contenus d’un support à l’autre. Il peut, par exemple, partir d’un tutoriel pour produire la transcription d’une vidéo YouTube. Ou reprendre un tutoriel très technique et le rendre un peu plus général pour un article de blog. La capture d’écran ci-dessous présente un exemple de prompt utilisé pour produire une transcription vidéo à partir de l’un de nos projets d’exemple. Cette approche nous épargne des heures de réécriture tout en préservant la cohérence de nos messages sur les différents canaux.
>_ You are using OpenAI Codex in ~/src/dagster
▌Review the example project: examples/docs_projects/project_dagster_modal_pipes
▌and produce a video transcript to teach users the core Dagster and Modal concept
▌covered. Break the transcript into sections, and include code snippets to be
▌showcased in the video. The prose of the script should be fun but professional.
▌Save this to 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)Consultez la transcription complète de la vidéo ici !
Évaluer la couverture de la documentation
L’un de nos usages les plus expérimentaux de Codex consiste à nous en servir pour estimer ce qu’un humain peut comprendre.
En fournissant la documentation à Codex comme référence faisant autorité et comme contexte de départ, nous pouvons lui faire générer du code. Par exemple, les utilisateurs se servent souvent de Dagster pour exécuter et superviser leurs modèles de données dbt aux côtés d’autres programmes de traitement des données.
Nous demandons à Codex de s’appuyer sur la documentation pour produire le code de ce projet, puis nous pouvons exécuter une suite de tests sur le code obtenu afin de vérifier qu’il fonctionne comme prévu. Si c’est le cas, nous pouvons supposer que notre documentation couvre suffisamment les sujets nécessaires. Si Codex parvient à générer du code fonctionnel à partir de notre seule documentation, c’est un indice solide que les humains peuvent en faire autant. Cela nous donne une mesure indirecte du degré d’exhaustivité de notre documentation.
Résumé
Dans l’ensemble, l’équipe Dagster a trouvé Codex extrêmement utile pour créer, réviser et adapter des contenus pédagogiques. Il nous a permis de produire davantage que nous ne le pouvions auparavant et nous a aidés à maintenir une couverture suffisante de la documentation à mesure que le framework évolue. Surtout, il nous permet d’accompagner plus facilement notre communauté.
Codex a mis en évidence l’importance du contexte et de la structure. Pour nous, cela signifie affiner l’architecture de notre documentation afin que les humains comme l’IA puissent s’y repérer facilement. Cette boucle de rétroaction alimentée par l’IA a amélioré à la fois notre façon de créer du contenu et celle dont les utilisateurs génèrent du code pour le framework. À mesure que les outils d’IA évoluent, la frontière entre documentation, code et automatisation s’estompera. Les équipes qui traitent la documentation comme des données structurées auront un avantage majeur.