在 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
...您可以在 dagster-io/dagster # 32558 查看这次会话生成的 Pull Request。
在不同内容媒介之间转换
不同类型的用户偏好不同的学习形式，但要传达的核心概念往往相同。因此，我们制作了多种形式的内容：博客文章、教程、在线课程、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 工具不断发展，文档、代码和自动化之间的界限将逐渐模糊。将文档视为结构化数据的团队将拥有显著优势。