在 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 requests,或指定程式碼庫中的某個部分請它說明,都是它最能幫上忙的地方。
我們常用的一個技巧,是請 Codex 執行 gh 指令來解讀 pull requests。可以請它查看 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
▌ 請用 `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 影片講稿,也可以把深入實作細節的教學改寫成部落格文章,讓重點稍微轉向背後的概念。下方畫面中的提示詞示範了我們如何請 Codex 根據一個範例專案撰寫影片講稿。這種做法能省下好幾個小時的改寫時間,也讓我們在各個管道傳達的訊息保持一致。
>_ 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 工具演進,文件、程式碼與自動化之間的界線將逐漸模糊。把文件當成結構化資料來處理的團隊,將擁有很大的優勢。