Na Dagster Labs, produzimos bastante material didático para ajudar engenheiros de dados, engenheiros de aprendizado de máquina e analistas a entender melhor como usar o Dagster, um framework de código aberto para orquestração de fluxos de trabalho. Como nossos usuários têm experiências técnicas variadas, percebemos que é essencial ajustar o nível de detalhe ao perfil de cada público.
Neste post, vou mostrar como usamos o Codex da OpenAI para agilizar a produção de documentação, adaptar conteúdo a diferentes formatos e até avaliar se nossa documentação está completa.
O valor dos arquivos CONTRIBUTING.md
Para que os membros da comunidade e nossos engenheiros pudessem contribuir com a documentação com mais facilidade, reformulamos nosso arquivo CONTRIBUTING.md. Para nossa surpresa, essa mudança também tornou o Codex muito mais útil. Explicar como a documentação está organizada na base de código, qual é sua hierarquia e quais boas práticas seguir ao escrever ajuda tanto as pessoas quanto os robôs.
# 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
...A qualidade do trabalho do Codex depende da estrutura que você oferece a ele. Um CONTRIBUTING.md bem organizado serve de documentação para as pessoas e de mapa para a IA.
Como o Codex ajuda a entender o código
Além de escrever documentação, o Codex está sempre disponível para explicar como o código funciona. Para quem trabalha com relações com desenvolvedores ou redação técnica, isso tem sido valioso. Em projetos de código aberto ou com muitos engenheiros, costuma ser difícil acompanhar todos os recursos em desenvolvimento e entender como cada um funciona. Isso vale especialmente para equipes pequenas de relações com desenvolvedores e redação técnica. Duas das formas mais úteis de obter ajuda do Codex são pedir que ele explique um pull request ou indicar um trecho da base de código e pedir que explique como ele funciona.
Uma dica que tem funcionado para nós é usar o comando gh no Codex para entender pull requests. Peça ao Codex que examine a descrição e o diff do PR, resuma o motivo da implementação do recurso e explique como disponibilizá-lo aos usuários finais.
As vantagens de um monorepo
Sei que o assunto divide opiniões, mas sou fã de monorepos. Quando o contexto é essencial, fica muito mais fácil encontrar o que você precisa se tudo está acessível em um único repositório. Para o Codex, isso significa ter todo o contexto à disposição, com código, documentação e exemplos no mesmo lugar.
Algumas pessoas já manifestaram preocupação com a capacidade de ferramentas como o Codex de acompanhar o crescimento dos repositórios. Na minha experiência, isso não tem sido um problema. Com as referências a arquivos do Codex (@), você pode indicar um subdiretório ou arquivo como ponto de partida para ele explorar o restante do repositório. Manter o código do framework e a documentação no mesmo repositório também traz vantagens importantes. Podemos pedir ao Codex que leia o código do framework e esboce a estrutura da documentação, que depois refinamos.
No exemplo a seguir, pedimos ao Codex que examinasse um pull request existente e acrescentasse à documentação uma seção explicando como usar as variáveis de ambiente em questão para configurar a implantação.
>_ 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
▌ Use `gh pr diff <number>` para revisar as alterações do pull request 32557. Examine as variáveis de ambiente
▌ novas e as que já existiam para configurar o servidor gRPC. Em seguida, atualize a página
▌ docs/docs/deployment/oss/oss-instance-configuration.md para descrever as opções de configuração.
> 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
...Você pode consultar o pull request criado nessa sessão em dagster-io/dagster # 32558.
Como adaptar conteúdo a diferentes formatos
Cada público tem suas preferências na hora de aprender, mas as ideias que queremos transmitir muitas vezes são as mesmas. Por isso, produzimos conteúdo em vários formatos, como posts de blog, tutoriais, cursos online e vídeos no YouTube. Muitas vezes, o conteúdo central desses materiais é o mesmo. O que muda é a forma de apresentá-lo a cada público.
O Codex se sai muito bem nessa adaptação. Ele pode, por exemplo, transformar um tutorial em roteiro para um vídeo no YouTube ou adaptar um tutorial técnico para um post de blog, deixando de lado alguns detalhes de implementação. Na captura de tela abaixo, você encontra o prompt que usamos para criar um roteiro de vídeo a partir de um dos nossos projetos de exemplo. Essa abordagem poupa horas de reescrita e mantém a mensagem consistente em todos os canais.
>_ You are using OpenAI Codex in ~/src/dagster
▌Examine o projeto de exemplo em examples/docs_projects/project_dagster_modal_pipes
▌e escreva um roteiro de vídeo para ensinar aos usuários o conceito central de Dagster e Modal
▌que o projeto ilustra. Divida o roteiro em seções e inclua trechos de código para mostrar
▌no vídeo. Use um tom descontraído, mas profissional.
▌Salve o roteiro em 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)Confira o roteiro completo do vídeo!
Como avaliamos a cobertura da documentação
Um dos usos mais experimentais que fazemos do Codex é estimar, de forma indireta, o que uma pessoa consegue entender ao ler a documentação.
Podemos pedir ao Codex que gere código usando a documentação como referência oficial e contexto de partida. Por exemplo, é comum usar o Dagster para executar e monitorar modelos de dados do dbt junto com o restante do código de processamento de dados.
Pedimos ao Codex que consulte a documentação e gere o código desse projeto. Em seguida, executamos uma suíte de testes para verificar se o código se comporta como esperado. Se os testes passarem, podemos supor que a documentação cobre o conteúdo necessário. Se o Codex consegue gerar código funcional usando apenas a documentação, há um forte indício de que uma pessoa também conseguiria. Isso nos dá uma medida indireta de quão completa está a documentação.
Resumo
Para a equipe da Dagster, o Codex tem sido de grande ajuda na criação, revisão e adaptação de conteúdo educacional para diferentes formatos. Com ele, conseguimos produzir mais do que antes e verificar se a documentação continua cobrindo o necessário à medida que o framework evolui. E, o mais importante, ficou mais fácil dar suporte à nossa comunidade.
O uso do Codex reforçou a importância do contexto e da estrutura. Para nós, isso significa aprimorar a organização da documentação para que tanto as pessoas quanto a IA consigam navegar por ela com facilidade. Esse ciclo de feedback com a IA melhorou tanto a forma como criamos conteúdo quanto a maneira como os usuários geram código para o framework. À medida que as ferramentas de IA evoluírem, os limites entre documentação, código e automação ficarão menos nítidos. As equipes que tratarem a documentação como dados estruturados terão uma grande vantagem.