Dagster Labs에서는 데이터 엔지니어, 머신러닝 엔지니어, 분석가가 오픈 소스 워크플로우 오케스트레이션 프레임워크인 Dagster를 더 잘 활용할 수 있도록 다양한 기술 교육 콘텐츠를 만듭니다. 사용자마다 기술적 배경이 다르다 보니, 독자층에 맞춰 어느 정도 깊이까지 설명할지 정하는 일이 중요합니다.
이 글에서는 저희가 OpenAI의 Codex로 문서 작성 속도를 높이고, 콘텐츠를 다른 매체에 맞게 바꾸고, 문서가 필요한 내용을 얼마나 충실히 다루는지 평가하는 방법을 소개합니다.
CONTRIBUTING.md 파일의 가치
커뮤니티 구성원과 사내 엔지니어가 문서 작성에 더 쉽게 참여할 수 있도록 CONTRIBUTING.md 파일을 전면 개편했습니다. 뜻밖에도 이 작업 덕분에 Codex까지 훨씬 유용해졌습니다. 코드베이스에서 문서가 어떤 계층과 구조로 구성되는지, 문서를 작성할 때 어떤 방식을 권장하는지 명확히 설명해 두면 사람과 AI 모두에게 큰 도움이 됩니다.
# 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의 내용을 설명해 달라고 하거나 코드베이스에서 궁금한 부분을 짚어 설명을 요청하는 방법이 특히 유용했습니다.
pull request를 이해하고 싶다면 Codex 안에서 gh 명령어를 활용해 보세요. Codex에 PR 설명과 diff를 검토한 다음, 기능을 구현한 이유를 요약하고 최종 사용자에게 어떤 방식으로 제공해야 할지 설명해 달라고 요청하세요.
모노레포의 장점
의견이 갈릴 수도 있지만, 저는 모노레포를 무척 좋아합니다. 컨텍스트가 중요한 작업에서는 모든 자료가 한 리포지터리에 있으면 필요한 내용을 훨씬 쉽게 찾을 수 있습니다. Codex 역시 코드와 문서, 예제를 한곳에서 살펴보며 전체 컨텍스트를 파악할 수 있습니다.
리포지터리 규모가 커지면 Codex 같은 도구를 쓰기 어렵지 않겠느냐는 우려도 있지만, 제 경험은 달랐습니다. Codex의 파일 참조 기능(@)으로 처음 살펴볼 하위 디렉터리나 파일을 지정하면, Codex가 거기서 시작해 탐색 범위를 넓혀 갈 수 있습니다. 프레임워크 코드와 문서를 한 리포지터리에 두면 얻는 이점도 큽니다. 저희는 Codex에 프레임워크 코드를 읽고 문서의 기본 틀을 잡아 달라고 요청한 뒤, 그 초안을 다듬습니다.
아래는 Codex에 기존 pull request를 검토하고, 여기에 나온 환경 변수가 배포 설정에 구체적으로 어떻게 쓰이는지 설명하는 절을 문서에 추가해 달라고 요청한 예입니다.
>_ 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
▌ `gh pr diff <number>`를 사용해 pull request 32557의 변경 사항을 검토하세요.
▌ gRPC 서버 설정에 쓰이는 환경 변수 중 새로 추가된 변수와 기존 변수를 모두 확인한 다음,
▌ docs/docs/deployment/oss/oss-instance-configuration.md 페이지에 설정 옵션을 정리하세요.
> 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
...이 세션에서 만든 pull request는 dagster-io/dagster # 32558에서 확인할 수 있습니다.
매체에 맞게 콘텐츠 바꾸기
독자층마다 선호하는 학습 방식은 다르지만, 배워야 할 개념은 같은 경우가 많습니다. 그래서 저희는 블로그 글, 튜토리얼, 온라인 강좌, YouTube 동영상 등 다양한 형식으로 콘텐츠를 만듭니다. 같은 핵심 내용을 다루더라도 누구를 위한 자료인지에 따라 전달 방식을 달리합니다.
Codex는 콘텐츠를 다른 매체에 맞게 바꾸는 일을 특히 잘합니다. 예를 들어 튜토리얼로 YouTube 동영상 대본을 만들거나, 구현 세부 사항을 다룬 튜토리얼을 핵심 개념에 조금 더 초점을 맞춘 블로그 글로 바꿀 수 있습니다. 아래 화면은 저희 예제 프로젝트 중 하나를 바탕으로 동영상 대본을 만들 때 사용한 프롬프트입니다. 이렇게 하면 채널마다 전달하는 메시지를 일관되게 유지하면서도 같은 내용을 다시 쓰는 데 드는 시간을 몇 시간씩 줄일 수 있습니다.
>_ You are using OpenAI Codex in ~/src/dagster
▌예제 프로젝트 examples/docs_projects/project_dagster_modal_pipes를 검토하고,
▌이 예제에서 다루는 Dagster와 Modal의 핵심 개념을 사용자에게 설명하는 동영상 대본을 작성하세요.
▌대본을 여러 절로 나누고 동영상에서 보여 줄 코드 스니펫을 포함하세요.
▌대본은 흥미로우면서도 전문적인 어조로 작성하세요.
▌완성한 대본을 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 도구가 발전할수록 문서와 코드, 자동화 사이의 경계는 흐려질 것입니다. 문서를 구조화된 데이터로 다루는 팀은 큰 이점을 누리게 될 것입니다.