在 Dagster Labs 使用 Codex 进行教育

在 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 命令来解释拉取请求。让它审查 PR 描述和差异（diff），总结该功能实现的原因，并解释它应如何暴露给最终用户。

单体仓库（mono repo）的力量

这可能是一个有争议的观点，但我非常推崇单体仓库。当上下文至关重要时，将所有内容集中在一个仓库中，能让你更轻松地获取所需内容；对于 Codex 而言，这意味着完整的上下文：代码、文档和示例都集中在一处。

虽然有人担心像 Codex 这样的工具无法随仓库规模扩展，但我发现情况并非如此。通过在 Codex 中使用文件引用（@），你可以先给 Codex 一个初始的子目录或文件，让它在此基础上进一步探索。将框架代码与文档放在同一个仓库中，还有一些实实在在的好处。这种设置让我们可以提示 Codex 阅读框架代码，并起草初始的文档框架，随后我们再对其进行完善。

下面是一个示例，我们提示 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

  ...

你可以在 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 工具的演进，文档、代码和自动化之间的界限将变得模糊。将文档视为结构化数据的团队将拥有巨大优势。