Dagster Labs では、データエンジニア、機械学習エンジニア、アナリストに向けて、オープンソースのワークフローオーケストレーションフレームワークである Dagster の使い方を学べる教材を数多く制作しています。ユーザーの技術的なバックグラウンドはさまざまなので、想定する読者に合わせて、どこまで技術的な詳細に踏み込むかを調整することが欠かせません。
この記事では、私たちが OpenAI の Codex を使ってドキュメントの作成を効率化し、同じ教材をさまざまな形式に展開する方法を紹介します。さらに、ドキュメントが必要な情報をどこまで網羅しているかを測る試みも取り上げます。
CONTRIBUTING.md の役割
コミュニティのメンバーや社内のエンジニアがドキュメントの執筆に参加しやすくなるよう、私たちは CONTRIBUTING.md を全面的に見直しました。意外にも、その結果、Codex から得られる支援の質も大きく向上しました。コードベース内のドキュメントについて、階層構造や構成、執筆時に推奨する書き方を明示しておくことは、人間にとっても AI にとっても大きな意味があります。
# 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
...Codex がどこまで力を発揮できるかは、作業の指針をどれだけ明確に示せるかにかかっています。構成のよい CONTRIBUTING.md は、人間にとっては執筆ガイドになり、AI にとってはコードベースをたどるための地図になります。
Codex を使ったコードの理解
Codex はドキュメントを書くときだけでなく、コードの説明が欲しいときにも、いつでも頼れます。これはデベロッパーアドボケイトやテクニカルライターにとって、非常に役立っています。オープンソースプロジェクトや多くのエンジニアが参加するプロジェクトでは、開発中の機能をすべて把握し、それぞれの仕組みまで理解し続けるのは容易ではありません。デベロッパーアドボケイトやテクニカルライターが少人数で対応している場合はなおさらです。私たちが特に助かっているのは、pull requests の内容を解説してもらったり、コードベースの特定の箇所を指定して仕組みを説明してもらったりできることです。
pull requests を解説してもらうときのコツは、Codex 内で gh コマンドを使うことです。PR の説明と差分を確認したうえで、その機能を実装した理由を要約し、エンドユーザーにどのような形で提供すべきかを説明するよう依頼します。
モノレポの利点
意見が分かれるかもしれませんが、私はモノレポがとても気に入っています。コンテキストが重要な場面では、すべてが同じリポジトリにあると、必要な情報をずっと簡単に見つけられます。Codex にとっては、コード、ドキュメント、サンプルが一か所にそろい、コンテキストの全体像を把握できるということです。
リポジトリが大きくなると Codex のようなツールでは対応しきれなくなるという声もありますが、私の経験ではそうした問題は起きていません。Codex のファイル参照機能（@）を使えば、まず調べてほしいサブディレクトリやファイルを指定し、そこから調査範囲を広げてもらえます。また、フレームワークのコードとドキュメントを同じリポジトリに置くことには、大きな利点があります。Codex にフレームワークのコードを読んでドキュメントのたたき台を作るよう依頼し、それを私たちの手で仕上げられます。
次の例では、既存の pull request を確認し、そこで扱われている環境変数がデプロイの設定にどう役立つかを具体的に説明するセクションをドキュメントに追加するよう、Codex に依頼しました。
>_ 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
▌ `gh pr diff <number>` を使って pull request 32557 の変更内容を確認してください。
▌ gRPC サーバーの設定に使う環境変数を、新しく追加されたものと既存のものの両方について確認してください。
▌ そのうえで 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
...このセッションで作成した pull request は dagster-io/dagster # 32558 で確認できます。
教材の形式に合わせた書き換え
学びやすいと感じる形式は人によって異なりますが、学ぶ内容は共通していることがよくあります。そのため、私たちはブログ記事、チュートリアル、オンライン講座、YouTube 動画など、さまざまな形式で教材を制作しています。核となる内容は同じでも、誰に届けたいかに応じて伝え方を変えています。
Codex は、教材を別の形式に書き換える作業を得意としています。たとえば、チュートリアルをもとに YouTube 動画の台本を作ったり、実装の細部まで扱うチュートリアルを、少し視点を広げてブログ記事にまとめたりできます。以下は、私たちのサンプルプロジェクトの一つをもとに動画の台本を作成したときのプロンプトです。この方法なら、媒体が変わっても伝えたい内容の一貫性を保ちながら、書き直しにかかる時間を何時間も節約できます。
>_ You are using OpenAI Codex in ~/src/dagster
▌サンプルプロジェクト examples/docs_projects/project_dagster_modal_pipes を確認し、
▌そこで扱っている Dagster と Modal の基本概念をユーザーに解説する動画の台本を作成してください。
▌台本をセクションに分け、動画で紹介するコードスニペットを含めてください。
▌語り口は、専門家らしさを保ちつつ、楽しく聞けるものにしてください。
▌台本を 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)動画の台本全文をご覧ください。
ドキュメントの網羅性の評価
私たちが試している、やや実験的な使い方の一つに、読者がドキュメントからどこまで理解できるかを Codex の出力から推し量る方法があります。
ドキュメントを正しい情報のよりどころとし、Codex にコンテキストとして与えると、その内容に基づいてコードを生成できます。たとえば Dagster は、他のデータ処理コードと併せて dbt データモデルを実行し、その実行状況を監視するためによく使われます。
こうしたプロジェクトのコードをドキュメントに基づいて生成するよう Codex に依頼し、生成されたコードに対してテストスイートを実行すれば、期待どおりに動作するかを確認できます。期待どおりに動けば、そのプロジェクトに必要な情報はドキュメントで十分にカバーできていると考えられます。ドキュメントだけを頼りに Codex が動くコードを生成できるなら、人間にも同じことができる可能性は高いでしょう。それが、ドキュメントの網羅性を間接的に測る指標になります。
まとめ
Dagster チームでは、教材の作成、レビュー、別の形式への書き換えに Codex が大いに役立っています。以前の体制では手が回らなかった規模の教材を制作できるようになり、フレームワークが進化しても、ドキュメントが必要な情報を網羅しているかを確かめられるようになりました。何より、コミュニティを支援しやすくなりました。
Codex を使うなかで、コンテキストと構造の重要性を改めて実感しています。私たちは、人間も AI も必要な情報にたどり着きやすいよう、ドキュメントの構成を見直しています。AI を使ってドキュメントを改善し、その成果をまた活用するという循環が、私たちの教材制作と、ユーザーがフレームワークを使うコードを生成する作業の両方を改善してきました。AI ツールが進化するにつれ、ドキュメント、コード、自動化の境界は曖昧になっていくでしょう。ドキュメントを構造化データとして扱うチームは、大きな強みを持つことになります。