在 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 還能隨時協助解說程式碼。對開發者推廣人員和技術寫作者來說，這項能力非常寶貴。在開源專案或有許多工程師參與的專案中，要隨時掌握所有開發中的功能及其運作方式，往往並不容易。對規模較小的開發者推廣與技術寫作團隊來說，更是如此。我們發現，讓 Codex 解說 Pull Request，或指定程式碼庫中的某個部分請它說明，是它最能幫上忙的用法之一。
我們發現了一個實用技巧：在 Codex 中使用 gh 指令來解說 Pull Request。請它審查 PR 說明與程式碼差異，概述實作這項功能的原因，並說明應如何將功能提供給終端使用者。
單一程式碼庫的力量
這個看法可能有些爭議，但我非常喜歡單一程式碼庫。當上下文至關重要時，把所有內容放在同一個程式碼庫中，就能更輕鬆地取得所需資訊。對 Codex 而言，這代表完整的上下文：程式碼、文件和範例全都集中在一處。
有些人擔心，隨著程式碼庫規模擴大，Codex 這類工具會難以應付，但我的經驗並非如此。透過 Codex 的檔案參照功能（@），你可以先指定一個子目錄或檔案，讓 Codex 以此為起點，再進一步探索。此外，將框架程式碼與文件放在同一個程式碼庫中，也有很大的好處。這樣我們就能請 Codex 閱讀框架程式碼、草擬文件架構，再由我們進一步完善。
以下範例中，我們請 Codex 審查現有的 Pull Request，並在文件中新增一節，具體說明這些環境變數在設定部署時有何用途。
>_ 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 工具演進，文件、程式碼與自動化之間的界線將逐漸模糊。將文件視為結構化資料的團隊，將擁有顯著優勢。