En Dagster Labs, producimos mucho contenido educativo técnico para que los ingenieros de datos, los ingenieros de aprendizaje automático y los analistas comprendan mejor cómo usar Dagster, un framework de código abierto para la orquestación de flujos de trabajo. Como nuestros usuarios tienen distintos conocimientos técnicos, hemos comprobado que es fundamental ofrecer el nivel de profundidad técnica adecuado para cada perfil.
En esta publicación, compartiré cómo usamos Codex de OpenAI para agilizar la creación de documentación, adaptar contenido a distintos medios e incluso medir qué tan completa está nuestra documentación.
El poder de los archivos CONTRIBUTING.md
Para facilitar que los miembros de nuestra comunidad y los ingenieros de nuestro equipo contribuyeran a la documentación, renovamos por completo nuestro archivo CONTRIBUTING.md. Para nuestra sorpresa, sin proponérnoslo habíamos logrado que Codex fuera mucho más útil. Resulta que definir con claridad la jerarquía, la estructura y las prácticas recomendadas para escribir documentación en tu base de código tiene un gran valor. Tanto para humanos como para robots.
# 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
...La eficacia de Codex depende de la estructura de apoyo que le proporciones. Un CONTRIBUTING.md bien estructurado sirve tanto de documentación para las personas como de mapa para la IA.
Codex para comprender el código
Además de escribir documentación, Codex puede explicar código en cualquier momento. Para quienes trabajan en divulgación para desarrolladores y redacción técnica, esto ha sido invaluable. En proyectos de código abierto o con muchos ingenieros, suele ser difícil mantenerse al día con todas las funciones en desarrollo y entender cómo funcionan. Esto es especialmente cierto para los equipos pequeños de divulgación para desarrolladores y redacción técnica. Hemos comprobado que Codex resulta especialmente útil para explicar pull requests o partes de la base de código que le indicamos.
Un consejo que nos ha resultado útil es usar el comando gh desde Codex para explicar pull requests. Pídele que revise la descripción y el diff del PR, resuma por qué se implementó la función y explique cómo debería ponerse a disposición de los usuarios finales.
El poder del monorepositorio
Puede que sea una opinión polémica, pero soy un gran fan de los monorepositorios. Cuando el contexto es clave, tener todo disponible en un solo repositorio facilita mucho acceder a lo que necesitas. En el caso de Codex, esto significa disponer del contexto completo: código, documentación y ejemplos en un solo lugar.
Aunque algunas personas han expresado su preocupación por que herramientas como Codex no puedan adaptarse al crecimiento de los repositorios, en mi experiencia no ha sido así. Con las referencias a archivos de Codex (@), puedes indicarle el subdirectorio o archivo por el que debe empezar antes de explorar más a fondo. Además, tener el código del framework junto con la documentación en un solo repositorio ofrece grandes ventajas. Esta organización nos permite pedirle a Codex que lea el código del framework y redacte esquemas iniciales de documentación que luego podemos perfeccionar.
Aquí tienes un ejemplo en el que le pedimos a Codex que revisara un Pull Request existente y agregara una sección a la documentación sobre cómo ayudan exactamente estas variables de entorno al configurar tu despliegue.
>_ 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
...Puedes encontrar el Pull Request que se generó en esta sesión en dagster-io/dagster # 32558.
Adaptar contenido a distintos medios
Los distintos perfiles de usuario prefieren distintos formatos de aprendizaje, pero las ideas de fondo suelen ser las mismas. Por eso, producimos contenido en diversos medios: publicaciones de blog, tutoriales, cursos en línea, videos de YouTube y más. El contenido central de estos materiales suele ser el mismo; lo que cambia es cómo se presenta según el perfil al que va dirigido.
Codex funciona excepcionalmente bien para adaptar contenido entre estos medios. Por ejemplo, puede tomar un tutorial y producir una transcripción para un video de YouTube. O partir de un tutorial con detalles de bajo nivel y darle un enfoque un poco más general para una publicación de blog. En la siguiente captura de pantalla puedes ver un ejemplo de un prompt que usamos para convertir uno de nuestros proyectos de ejemplo en una transcripción de video. Este enfoque ahorra horas de reescritura y mantiene la coherencia de nuestros mensajes entre canales.
>_ 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)¡Consulta la transcripción completa del video aquí!
Evaluar la cobertura de la documentación
Uno de nuestros usos más experimentales de Codex consiste en emplearlo como indicador indirecto de la comprensión humana.
Al usar la documentación como fuente de referencia definitiva y contexto base para Codex, podemos pedirle que genere código. Por ejemplo, es habitual usar Dagster para ejecutar y monitorear modelos de datos de dbt junto con otro código de procesamiento de datos.
Al pedirle a Codex que consulte la documentación y produzca el código para este proyecto, podemos ejecutar después un conjunto de pruebas sobre el código resultante para comprobar que funciona como se espera. Si es así, podemos suponer que nuestra documentación cubre adecuadamente el contenido necesario. Si Codex puede generar código funcional basándose únicamente en nuestra documentación, es un indicio sólido de que las personas también pueden hacerlo, lo que nos permite medir indirectamente qué tan completa está la documentación.
Resumen
En general, el equipo de Dagster ha encontrado en Codex una ayuda enorme para crear, revisar y adaptar contenido educativo. Nos ha permitido superar nuestra capacidad original, nos ha ayudado a mantener una cobertura adecuada de la documentación a medida que evoluciona el framework y, lo más importante, nos ha facilitado brindar apoyo a nuestra comunidad.
Codex ha puesto de relieve la importancia del contexto y la estructura. Para nosotros, eso significa perfeccionar la arquitectura de nuestra documentación para que tanto las personas como la IA puedan recorrerla con facilidad. Este ciclo de retroalimentación, impulsado por IA, ha mejorado tanto nuestra forma de crear contenido como la manera en que los usuarios generan código del framework. A medida que evolucionen las herramientas de IA, los límites entre documentación, código y automatización se volverán más difusos. Los equipos que traten la documentación como datos estructurados tendrán una gran ventaja.