Chez Dagster Labs, nous produisons de nombreuses ressources pédagogiques pour aider les ingénieurs data, les ingénieurs en machine learning et les analystes à mieux utiliser Dagster, notre framework open source d’orchestration de workflows. Nos utilisateurs ont des parcours techniques variés. Il est donc essentiel d’adapter le niveau de détail de nos explications à chaque public.
Dans cet article, je vous montrerai comment nous utilisons Codex d’OpenAI pour rédiger plus vite notre documentation, adapter nos contenus à différents supports et même évaluer si notre documentation est complète.
L’intérêt des fichiers CONTRIBUTING.md
Pour que les membres de notre communauté et nos ingénieurs puissent plus facilement contribuer à la documentation, nous avons remanié notre fichier CONTRIBUTING.md. À notre surprise, ce travail a aussi rendu Codex bien plus utile. Expliquer clairement comment la documentation s’organise dans le dépôt, comment les différentes sections s’articulent et quelles pratiques de rédaction suivre aide autant les humains que 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 donnez. Un fichier CONTRIBUTING.md bien structuré sert à la fois de guide pour les contributeurs et de plan pour l’IA.
Comprendre le code avec Codex
Au-delà de la rédaction, Codex peut expliquer le code à tout moment. Cette aide s’est révélée précieuse pour les équipes chargées des relations avec les développeurs et de la rédaction technique. Dans un projet open source ou un projet qui mobilise de nombreux ingénieurs, il est souvent difficile de suivre toutes les fonctionnalités en développement et de comprendre leur fonctionnement. C’est particulièrement vrai lorsque peu de personnes se consacrent aux relations avec les développeurs ou à la documentation. Parmi les usages de Codex qui nous aident le plus, deux sont très simples : lui demander d’expliquer une pull request ou lui indiquer une partie du code source pour qu’il nous en détaille le fonctionnement.
Pour obtenir une explication d’une pull request, nous utilisons la commande gh depuis Codex. Demandez à Codex d’examiner la description de la PR et le diff, de résumer les raisons de l’ajout de la fonctionnalité et d’expliquer comment la rendre accessible aux utilisateurs finaux.
Les avantages du monorepo
Je sais que les avis divergent, mais j’apprécie beaucoup les monorepos. Quand le contexte compte, il est bien plus facile de trouver ce dont on a besoin si tout est accessible dans un seul dépôt. Codex dispose ainsi de tout le contexte : le code, la documentation et les exemples sont réunis au même endroit.
Certains craignent que des outils comme Codex perdent en efficacité à mesure que le dépôt grossit. Ce n’est pas ce que j’ai constaté. Grâce aux références de fichiers dans Codex (@), vous pouvez lui indiquer le sous-répertoire ou le fichier à examiner en premier avant de poursuivre son exploration. Réunir le code du framework et sa documentation dans un même dépôt présente aussi des avantages concrets. Nous pouvons ainsi demander à Codex de lire le code du framework et d’ébaucher une documentation que nous affinons ensuite.
Dans l’exemple suivant, nous avons demandé à Codex d’examiner une pull request existante, puis d’ajouter à la documentation une section expliquant précisément à quoi servent les variables d’environnement concernées lors de la configuration d’un 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
▌ Examinez les modifications de la pull request 32557 à l’aide de `gh pr diff <number>`. Passez en revue
▌ les variables d’environnement ajoutées et celles qui permettaient déjà de configurer le serveur gRPC.
▌ Mettez ensuite à jour la page docs/docs/deployment/oss/oss-instance-configuration.md pour y présenter les options de configuration.
> 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 issue de cette session sur GitHub : dagster-io/dagster # 32558.
Adapter un contenu à différents supports
Les formats d’apprentissage préférés varient d’un public à l’autre, mais les notions à transmettre sont souvent les mêmes. Nous proposons donc des articles de blog, des tutoriels, des cours en ligne, des vidéos YouTube et d’autres supports. Le fond reste souvent le même. C’est la façon de le présenter qui change selon le public visé.
Codex est particulièrement efficace pour passer d’un format à l’autre. Il peut, par exemple, transformer un tutoriel en script de vidéo YouTube ou reprendre un tutoriel détaillé et en dégager les grandes lignes pour un article de blog. La capture d’écran ci-dessous montre le prompt que nous avons utilisé pour rédiger un script vidéo à partir de l’un de nos projets d’exemple. Cette méthode nous épargne des heures de réécriture tout en préservant la cohérence de nos explications d’un support à l’autre.
>_ You are using OpenAI Codex in ~/src/dagster
▌Examinez le projet d’exemple examples/docs_projects/project_dagster_modal_pipes
▌et rédigez un script vidéo pour expliquer aux utilisateurs la notion fondamentale de Dagster
▌et de Modal qu’illustre ce projet. Découpez le script en sections et incluez les extraits
▌de code à montrer dans la vidéo. Adoptez un ton enjoué et professionnel.
▌Enregistrez le script dans 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 le script complet de la vidéo !
É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 lecteur peut comprendre à partir de notre documentation.
Nous donnons à Codex la documentation comme référence et comme contexte de départ, puis nous lui demandons de générer du code. Prenons un cas courant : les utilisateurs se servent souvent de Dagster pour exécuter et suivre leurs modèles de données dbt en parallèle d’autres traitements de données.
Nous demandons à Codex de consulter la documentation et d’écrire le code de ce projet. Nous exécutons ensuite une suite de tests pour vérifier que le code se comporte comme prévu. Si les tests passent, nous pouvons supposer que notre documentation couvre suffisamment les notions nécessaires. Si Codex parvient à produire du code fonctionnel en s’appuyant uniquement sur notre documentation, c’est un bon indice que nos lecteurs peuvent en faire autant. Nous disposons ainsi d’une mesure indirecte du degré de couverture de la documentation.
En résumé
Chez Dagster, Codex nous a beaucoup aidés à créer, à relire et à adapter nos contenus pédagogiques. Nous pouvons produire davantage de ressources qu’auparavant et vérifier que notre documentation couvre suffisamment les fonctionnalités du framework à mesure qu’il évolue. Surtout, il nous est désormais plus facile d’accompagner notre communauté.
Codex nous a fait prendre conscience de l’importance du contexte et de la structure. Nous affinons donc l’organisation de notre documentation pour que les lecteurs comme l’IA puissent s’y repérer facilement. Les enseignements que nous tirons de l’utilisation de l’IA pour améliorer la documentation nous aident à créer de meilleurs contenus et aident nos utilisateurs à générer du code pour le framework. À mesure que les outils d’IA évolueront, les frontières entre documentation, code et automatisation s’estomperont. Les équipes qui traitent leur documentation comme des données structurées auront une longueur d’avance.