私たち Dagster Labs は、データエンジニア、機械学習エンジニア、アナリストに向けて、技術教育コンテンツを数多く制作しています。オープンソースのワークフローオーケストレーションフレームワークである Dagster の使い方を、より深く理解してもらうためです。ユーザーの技術的な背景はさまざまなので、それぞれの読者層に合った深さで技術を説明することが欠かせません。
この記事では、OpenAI の Codex を活用してドキュメント制作を効率化し、コンテンツを異なるメディア向けに作り替え、さらにはドキュメントの網羅性を測定している方法を紹介します。
CONTRIBUTING.md ファイルの力
コミュニティのメンバーや社内のエンジニアがドキュメントに貢献しやすくなるよう、CONTRIBUTING.md ファイルを全面的に見直しました。すると驚いたことに、意図せず Codex の有用性も大きく向上していたのです。コードベース内のドキュメントの階層や構造、執筆のベストプラクティスを明確に示すことには、大きな価値があるとわかりました。人間にとっても、ロボットにとってもです。
# 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 Request の解説を頼んだり、コードベースの一部を指定して説明を求めたりすることが、Codex の特に役立つ使い方となっています。
ここで役立つコツは、Codex 内から gh コマンドを使って Pull Request を解説してもらうことです。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
▌ 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
...このセッションで作成された Pull Request は、dagster-io/dagster # 32558 で確認できます。
異なるメディアへのコンテンツ展開
好まれる学習形式は読者層によって異なりますが、伝える基本的な考え方は共通していることが多いものです。そのため、私たちはブログ記事、チュートリアル、オンライン講座、YouTube 動画など、さまざまなメディアでコンテンツを制作しています。これらの教材は、核となる内容は同じで、対象とする読者層に応じて見せ方を変えているだけの場合もよくあります。
Codex は、こうしたメディア間でコンテンツを作り替えることに非常に優れています。たとえば、チュートリアルをもとに YouTube 動画の台本を作ったり、実装の細部を扱うチュートリアルの抽象度を少し上げてブログ記事にしたりできます。下のスクリーンショットは、私たちのサンプルプロジェクトの一つをもとに動画の台本を作成するために使ったプロンプトの例です。この方法なら、メディアが変わってもメッセージの一貫性を保ちつつ、書き直しにかかる時間を何時間も削減できます。
>_ 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)動画の台本全文はこちらをご覧ください！
ドキュメントの網羅性の評価
より実験的な取り組みとして、Codex を使って人間がどこまで理解できるかを間接的に測ることも試しています。
ドキュメントを正しい情報の基準とし、Codex に与える基本のコンテキストとして使えば、それをもとにコードを生成させられます。たとえば、Dagster は、dbt のデータモデルをほかのデータ処理コードとともに実行し、監視するためによく使われています。
Codex にドキュメントを参照してこのプロジェクトのコードを作成するよう依頼し、生成されたコードに対してテストスイートを実行すれば、期待どおりに動作するか確認できます。期待どおりに動作すれば、必要な内容をドキュメントが十分に網羅していると考えられます。Codex がドキュメントだけを頼りに動くコードを生成できるなら、人間にも同じことができるという有力な手がかりになります。これが、ドキュメントの網羅性を間接的に測る指標となるのです。
まとめ
Dagster チームにとって、Codex は教育コンテンツの作成、レビュー、異なるメディアへの展開に非常に役立っています。従来の制作能力を超えて取り組みを広げられるようになり、フレームワークの進化に合わせてドキュメントの十分な網羅性を保つうえでも助けになっています。そして何より、コミュニティをより容易に支援できるようになりました。
Codex を通じて、コンテキストと構造の重要性を改めて実感しました。私たちにとって、それは人間も AI も必要な情報を見つけやすいように、ドキュメントの構成を磨くことを意味します。AI によるこのフィードバックの循環は、私たちのコンテンツ制作と、ユーザーによるフレームワークのコード生成の両方を改善しました。AI ツールが進化するにつれ、ドキュメント、コード、自動化の境界は曖昧になっていくでしょう。ドキュメントを構造化されたデータとして扱うチームは、大きな優位性を得るはずです。