En Dagster Labs, creamos mucho material educativo de carácter técnico para que ingenieros de datos, ingenieros de aprendizaje automático y analistas entiendan mejor cómo usar Dagster, un framework de código abierto para orquestar flujos de trabajo. Como la formación técnica de nuestros usuarios es diversa, hemos visto que es fundamental ajustar el nivel de detalle a cada público.
En este artículo, te contaré cómo usamos Codex de OpenAI para agilizar la creación de documentación, adaptar contenido a distintos formatos e incluso medir qué tan completa está nuestra documentación.
El valor de los archivos CONTRIBUTING.md
Para que tanto los miembros de nuestra comunidad como los ingenieros de nuestro equipo pudieran contribuir más fácilmente a la documentación, reescribimos nuestro archivo CONTRIBUTING.md. Para nuestra sorpresa, ese cambio también hizo que Codex nos resultara mucho más útil. Vale la pena explicar con claridad cómo se organiza la documentación en tu base de código, qué jerarquía sigue y cuáles son las buenas prácticas para redactarla. Eso ayuda tanto a las personas como a los 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 utilidad de Codex depende de la estructura que le des para trabajar. Un archivo CONTRIBUTING.md bien organizado sirve a la vez como documentación para las personas y como mapa para la IA.
Entender el código con Codex
Además de redactar documentación, Codex puede explicarte el código en cualquier momento. Esto ha sido de gran ayuda para quienes trabajan con comunidades de desarrolladores o redactan documentación técnica. 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 funciona cada una. Esto se nota especialmente en los equipos pequeños de divulgación y redacción técnica. Hemos descubierto que dos de las mejores formas de aprovechar Codex son pedirle que explique un pull request o señalarle una parte de la base de código para que explique cómo funciona.
Algo que nos ha servido es usar el comando gh desde Codex para que nos explique los pull requests. Pídele que revise la descripción del PR y el diff, resuma por qué se implementó la función y explique cómo ponerla a disposición de los usuarios finales.
Las ventajas de un monorepositorio
Tal vez no todos estén de acuerdo, pero me gustan mucho los monorepositorios. Cuando el contexto es fundamental, tener todo en un solo repositorio facilita mucho encontrar lo que necesitas. En el caso de Codex, eso significa que tiene todo el contexto a su alcance: el código, la documentación y los ejemplos están en un mismo lugar.
A algunas personas les preocupa que herramientas como Codex dejen de funcionar bien a medida que crecen los repositorios, pero mi experiencia ha sido distinta. Con las referencias a archivos de Codex (@), puedes indicarle en qué subdirectorio o archivo empezar antes de que explore el resto. Además, guardar el código del framework y la documentación en un mismo repositorio tiene ventajas importantes. Así podemos pedirle a Codex que lea el código del framework y prepare esquemas iniciales de la documentación que luego podemos pulir.
En este ejemplo, le pedimos a Codex que revisara un pull request existente y agregara una sección a la documentación para explicar exactamente para qué sirven estas variables de entorno al configurar un 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
▌ Usa `gh pr diff <number>` para revisar los cambios del pull request 32557. Revisa tanto las variables
▌ de entorno nuevas como las que ya existían para configurar el servidor gRPC. Luego actualiza la página
▌ docs/docs/deployment/oss/oss-instance-configuration.md para describir las opciones de configuración.
> 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 consultar el pull request que se creó en esta sesión en dagster-io/dagster # 32558.
Adaptar contenido a distintos formatos
Cada público tiene sus preferencias a la hora de aprender, pero los conceptos de fondo suelen ser los mismos. Por eso creamos contenido en distintos formatos: artículos de blog, tutoriales, cursos en línea, videos de YouTube y más. A menudo, el contenido central es el mismo y lo que cambia es la forma de presentarlo según el público al que va dirigido.
Codex es especialmente bueno para adaptar contenido de un formato a otro. Por ejemplo, puede convertir un tutorial en el guion de un video de YouTube o partir de un tutorial que profundiza en los detalles de implementación y presentar el tema de forma un poco más general en un artículo de blog. En la siguiente captura de pantalla puedes ver el prompt que usamos para generar el guion de un video a partir de uno de nuestros proyectos de ejemplo. Así ahorramos horas de reescritura y mantenemos un mensaje coherente en todos nuestros canales.
>_ You are using OpenAI Codex in ~/src/dagster
▌Revisa el proyecto de ejemplo examples/docs_projects/project_dagster_modal_pipes
▌y redacta el guion de un video para enseñar a los usuarios el concepto fundamental
▌de Dagster y Modal que ilustra el proyecto. Divide el guion en secciones e incluye
▌fragmentos de código para mostrar en el video. Usa un tono ameno pero profesional.
▌Guarda el guion en 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 el guion completo del video aquí!
Evaluar la cobertura de la documentación
Uno de los usos más experimentales que le damos a Codex es estimar qué podría entender una persona al leer nuestra documentación.
Si le damos la documentación como contexto de partida y fuente de referencia, podemos pedirle a Codex que genere código. Por ejemplo, muchas personas usan Dagster para ejecutar y monitorear sus modelos de datos de dbt junto con otro código de procesamiento de datos.
Le pedimos a Codex que consulte la documentación y genere el código de ese proyecto. Luego ejecutamos un conjunto de pruebas para comprobar si el código funciona como esperamos. Si las pruebas pasan, podemos suponer que nuestra documentación cubre el contenido necesario. Si Codex logra generar código que funciona basándose únicamente en nuestra documentación, es un buen indicio de que las personas también pueden hacerlo. Eso nos da una medida indirecta de qué tan completa está la documentación.
Resumen
En el equipo de Dagster, Codex nos ha resultado de gran ayuda para crear, revisar y adaptar contenido educativo a distintos formatos. Nos ha permitido producir más material del que podíamos crear antes y comprobar que la documentación siga cubriendo lo necesario a medida que evoluciona el framework. Y, sobre todo, nos ha facilitado la tarea de apoyar a nuestra comunidad.
Codex nos ha demostrado lo importantes que son el contexto y la estructura. Por eso seguimos afinando la arquitectura de nuestra documentación para que tanto las personas como la IA puedan orientarse en ella con facilidad. Este ciclo de retroalimentación con la IA ha mejorado tanto nuestra forma de crear contenido como la manera en que los usuarios generan código para el framework. A medida que evolucionen las herramientas de IA, los límites entre la documentación, el código y la automatización serán cada vez menos claros. Los equipos que traten la documentación como datos estructurados tendrán una gran ventaja.