在 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 阅读框架代码,拟出文档提纲,再由我们细化。
下面是一个例子。我们让 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 工具不断发展,文档、代码和自动化之间的界限将逐渐模糊。把文档当作结构化数据来管理的团队将拥有显著优势。