Na Dagster Labs, produzimos muito conteúdo técnico educacional 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 diferentes formações técnicas, percebemos que é essencial oferecer o nível de aprofundamento adequado a cada perfil.
Neste post, vou compartilhar como usamos o Codex da OpenAI para acelerar a produção de documentação, adaptar conteúdo para diferentes formatos e até medir o quanto nossa documentação está completa.
O poder dos arquivos CONTRIBUTING.md
Para facilitar as contribuições de membros da comunidade e engenheiros da nossa equipe para a documentação, reformulamos nosso arquivo CONTRIBUTING.md. Para nossa surpresa, sem querer, tornamos o Codex muito mais útil. Descobrimos que definir com clareza a hierarquia, a estrutura e as práticas recomendadas para escrever documentação na base de código traz grandes benefícios. Tanto para humanos quanto para 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 estruturado serve tanto como documentação para humanos quanto como um mapa para a IA.
Codex para entender o código
Além de escrever documentação, o Codex pode explicar código a qualquer momento. Para profissionais de relações com desenvolvedores e de redação técnica, isso tem sido extremamente valioso. Em projetos de código aberto ou com muitos engenheiros, pode ser difícil acompanhar todos os recursos em desenvolvimento e entender como funcionam. Isso vale especialmente para equipes menores de relações com desenvolvedores e redação técnica. Descobrimos que uma das melhores formas de obter ajuda do Codex é pedir que ele explique pull requests ou indicar um trecho da base de código e solicitar uma explicação.
Uma dica que descobrimos é usar o comando gh no Codex para explicar pull requests. Peça que ele revise a descrição e o diff do PR, resuma por que o recurso foi implementado e explique como ele deve ser disponibilizado aos usuários finais.
O poder do monorepo
Pode ser uma opinião controversa, mas sou um grande fã de monorepos. Quando o contexto é fundamental, ter tudo acessível em um único repositório facilita muito encontrar o que você precisa. No caso do Codex, isso significa contexto completo: código, documentação e exemplos em um só lugar.
Embora algumas pessoas tenham manifestado preocupação com a capacidade de ferramentas como o Codex de acompanhar o crescimento dos repositórios, não foi isso que observei. Usando referências a arquivos no Codex (@), você pode indicar o subdiretório ou arquivo por onde ele deve começar antes de explorar mais a fundo. E há grandes vantagens em manter o código do framework junto da documentação em um único repositório. Essa organização nos permite pedir ao Codex que leia o código do framework e crie esboços iniciais de documentação que podemos depois aprimorar.
Veja um exemplo em que pedimos ao Codex que revisasse um pull request existente e adicionasse uma seção à documentação explicando exatamente como essas variáveis do ambiente são úteis na configuração da 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
▌ 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
...Você pode encontrar o pull request produzido nesta sessão em dagster-io/dagster # 32558.
Adaptação de conteúdo para diferentes formatos
Pessoas com diferentes perfis preferem formatos de aprendizagem distintos, mas as ideias centrais costumam ser as mesmas. Por isso, produzimos conteúdo em vários formatos: posts de blog, tutoriais, cursos on-line, vídeos no YouTube e muito mais. O conteúdo central desses materiais muitas vezes pode ser o mesmo, apenas apresentado de outra forma conforme o público-alvo.
O Codex é excepcionalmente bom em adaptar conteúdo entre esses formatos. Por exemplo, transformar um tutorial em uma transcrição para um vídeo no YouTube. Ou partir de um tutorial com detalhes de implementação e torná-lo um pouco mais abstrato para um post de blog. Na captura de tela abaixo, você encontra um exemplo de prompt usado para transformar um dos nossos projetos de exemplo em uma transcrição de vídeo. Essa abordagem economiza horas de reescrita e mantém nossa mensagem consistente entre os canais.
>_ 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)Veja a transcrição completa do vídeo aqui!
Avaliação da cobertura da documentação
Um dos usos mais experimentais que estamos fazendo do Codex é como indicador indireto da compreensão humana.
Ao usar a documentação como fonte de verdade e contexto de base para o Codex, podemos pedir que ele gere código. Por exemplo, as pessoas costumam usar o Dagster para executar e monitorar seus modelos de dados dbt junto de outros códigos de processamento de dados.
Depois de pedir ao Codex que consulte a documentação e produza o código desse projeto, podemos executar uma suíte de testes no código gerado para verificar se ele funciona como esperado. Se funcionar, podemos supor que nossa documentação cobre adequadamente o conteúdo necessário. Se o Codex consegue gerar código funcional usando apenas nossa documentação, isso é um forte sinal de que humanos também conseguem, o que serve como uma medida indireta de quanto a documentação está completa.
Resumo
De modo geral, a equipe da Dagster considera o Codex extremamente útil para criar, revisar e adaptar conteúdo educacional. Ele nos permitiu ampliar nossa produção além da capacidade original, ajudou a garantir uma cobertura adequada da documentação à medida que o framework evolui e, mais importante, facilitou o apoio à nossa comunidade.
O Codex reforçou a importância do contexto e da estrutura. Para nós, isso significa aprimorar a arquitetura da documentação para que tanto humanos quanto IA possam navegar por ela com facilidade. Esse ciclo de feedback, impulsionado pela IA, melhorou tanto a forma como criamos conteúdo quanto a forma como os usuários geram código para o framework. Conforme as ferramentas de IA evoluem, as fronteiras entre documentação, código e automação ficarão menos nítidas. As equipes que tratarem a documentação como dados estruturados terão uma grande vantagem.