개발자가 실제로 보는 API 문서 영상 만들기

문서화된 API 레퍼런스는 정확하고 완전하지만, 그것만으로 시작하기는 거의 불가능합니다. 엔드포인트 목록을 처음 본 개발자는 모든 필드의 의미를 알면서도, API를 쓰는 첫 5분이 어떤 모습인지는 전혀 모릅니다.

짧은 영상은 바로 그 간극을 메웁니다. 레퍼런스를 대체하는 것이 아니라 보완하는 것입니다. 실제 키, 실제 요청, 실제 응답을 보여주는 3분짜리 영상은 레퍼런스가 답할 수 없는 질문에 답합니다. 내가 생각한 대로 정말 동작하는가?

이런 영상을 계속 쓸모 있게 만드는 방법을 정리했습니다.

어떤 내용을 영상으로 만들지 정하기

영상은 유지 비용이 큽니다. 텍스트가 가장 약한 지점에 투자하세요.

• 첫 성공 호출: 빈 터미널에서 200 응답까지. 만들 수 있는 가장 가치 있는 영상 하나입니다
• 인증 흐름: OAuth 리디렉션, 토큰 교환, 갱신 로직은 ‘순서’입니다. 순서야말로 영상의 영역입니다
• 여러 단계 워크플로: 리소스 생성, 상태 폴링, 결과 조회. 레퍼런스에서는 서로 무관한 세 엔드포인트로 보입니다
• 웹훅과 콜백: 두 시스템이 주고받는 과정은 글로 설명하기 정말 어렵습니다
• 흔한 실패: 401이 발생하고 고치는 영상 하나가 그에 관한 문단보다 더 많은 문의를 줄여줍니다

영상으로 만들 필요가 없는 것: 개별 엔드포인트 파라미터, enum 값, 레이트 리밋 수치. 검색하고 복사하고 몇 초 만에 고칠 수 있는 텍스트에 두세요.

녹화용 샌드박스 준비하기

실제 키로 프로덕션에 대고 녹화하지 마세요. 녹화 버튼을 누르기 전에 전용 환경을 만드세요.

• 일회용 샌드박스 계정 사용, 키는 녹화 직후 바로 교체
• 현실적인 데이터 넣기: test_user_1과 "foo"는 데모를 가짜처럼 보이게 합니다. 그럴듯한 이름, 금액, 타임스탬프가 신뢰를 만듭니다
• 짧은 수명의 키 형식이 있다면 사용해서, 토큰이 한 프레임 노출돼도 문제가 없게 만드세요
• 셸 환경 확인: env 출력과 셸 히스토리는 어떤 코드 샘플보다 많은 자격 증명을 유출해 왔습니다
• 캐시와 의존성 미리 준비해서 설치 과정을 녹화하지 않도록
• 알림 끄기 — 공개된 영상에 뜬 Slack 미리보기는 실제로 일어나는 사고입니다

샌드박스라도 모든 프레임이 공개된다고 가정하세요. 누군가는 반드시 일시정지합니다.

알맞은 캡처 설정 고르기

API 데모에는 보통 두세 개의 화면이 등장합니다. 터미널, 에디터, Postman이나 Insomnia 같은 API 클라이언트, 그리고 대시보드용 브라우저.

• 화면별 윈도우 캡처로 프레임을 좁게 유지하고 어질러진 데스크톱을 숨기세요
• 앱을 전환해야 한다면 미리 나란히 배치하고 둘을 포함하는 영역 캡처를 쓰세요. 녹화 중 알트탭은 시청자를 혼란스럽게 합니다
• 텍스트 위주라면 30fps로 충분하고, 낮은 프레임레이트는 더 선명한 글자에 비트레이트를 씁니다
• 네이티브 해상도로 녹화 — 나중에 확대하는 것이 흐릿함의 원인입니다
• 폰트를 18~24pt로 키우세요. 모니터에서 과하게 보이는 크기가 영상에서는 딱 적당합니다

모든 클립을 같은 구조로

일관성이 있어야 스크린캐스트 모음이 아니라 ‘문서’처럼 느껴집니다. 믿을 만한 4단계 구조는 이렇습니다.

1. 목표를 한 문장으로: “고객을 만들고 결제를 청구해 보겠습니다.”
2. 인증 보여주기: 헤더 하나뿐이어도 보여주세요. 키가 어디에 들어가는지 봐야 합니다
3. 요청을 실시간으로 구성: 직접 입력하거나 붙여넣고 각 필드를 설명하세요. 그 파라미터가 왜 필요한지 말하세요
4. 응답을 소리 내어 읽기: JSON에서 잠시 멈추세요. 다음 단계에 쓰일 필드를 짚어주세요

그리고 다음 내용을 예고하며 끝내세요. “이 id를 결제에 사용할 겁니다. 다음 영상에서 다룹니다.”

JSON과 코드를 읽기 쉽게

대부분의 API 영상이 실패하는 지점입니다. 요청은 성공했고, 응답이 화면을 가득 채우고, 시청자는 읽을 수 없는 중괄호 벽을 봅니다.

• 전부 정렬해서 출력: jq로 파이프하거나 클라이언트의 포매팅을 켜세요
• 중요하지 않은 부분은 접기: 대부분의 API 클라이언트는 섹션 접기를 지원합니다. 아무도 신경 쓰지 않는 메타데이터는 접으세요
• 핵심 필드에 줌: 중요한 두 줄에 준 줌 효과가 어떤 설명보다 낫습니다. Recorded에서는 녹화 후 에디터에서 줌을 추가하면 되니, 녹화 중에는 호출을 제대로 하는 데만 집중하세요
• 필드 이름은 텍스트 오버레이로: subscription_status를 가리키는 라벨이 말로 하는 것보다 빨리 읽힙니다
• 대기 시간 잘라내기: 네트워크 지연, 폴링 루프, 리빌드는 빈 시간입니다. 잘라내고 짧은 자막으로 경과 시간을 알려주세요

명세서가 아니라 동료처럼 설명하기

형식적인 설명은 이미 레퍼런스에 있습니다. 내레이션은 문서가 말할 수 없는 것을 말해야 합니다.

• “이 헤더가 다들 빠뜨리는 그 헤더입니다.”
• “네, 선택처럼 보이지만 이 필드는 필수입니다.”
• “여기서 422가 뜬다면 거의 항상 날짜 형식 문제입니다.”

이런 코멘트가 사실 문서 영상의 진짜 결과물입니다. 녹화 전에 서너 개를 미리 적어두세요. 정확히 입력하는 데 집중하다 보면 잊어버리기 쉽습니다.

짧고 모듈화된 클립으로

20분짜리 “API 전체 둘러보기”는 엔드포인트 하나만 바뀌어도 수명이 끝납니다. 하나의 작업만 다루는 2~4분 클립이 훨씬 오래 살아남고, 그 내용을 설명하는 레퍼런스 섹션 바로 옆에 붙일 수 있습니다.

모듈화는 곧 재녹화 가능성입니다. 페이로드 형태가 바뀌면 긴 영상을 편집하는 대신 90초짜리 클립 하나만 다시 찍으면 됩니다.

API 변경을 미리 감안하기

문서 영상은 문서 텍스트보다 빨리 낡습니다. 처음부터 대비하세요.

• 버전 번호를 말하고 화면에도 표시해서, 오래된 영상은 한눈에 오래됐다는 걸 알 수 있게
• 낡아 보일 UI 요소는 피하기 — 대시보드 리디자인이 API 변경보다 영상을 빨리 늙게 만듭니다
• 내보낸 파일뿐 아니라 원본 녹화와 프로젝트 파일 보관 — 재편집이 재촬영이 되지 않도록
• 엔드포인트와 버전으로 파일명 지정해서 릴리스 후 무엇을 갱신할지 바로 찾을 수 있게
• 메이저 버전이 올라갈 때마다 클립 검토하고 이제 틀린 내용은 다시 녹화

지난 분기에 만든 짧고 정직한 영상은 괜찮습니다. 이제는 없는 엔드포인트를 당당하게 보여주는 영상은 신뢰를 잃게 합니다.

질문이 생기는 곳에 게시하기

가장 잘 배치된 API 영상은 아무도 찾지 않는 별도 영상 라이브러리가 아니라 해당 엔드포인트의 레퍼런스 페이지에 바로 임베드된 영상입니다. 2분이 넘으면 챕터나 타임스탬프를 넣고, 영상에 나온 전체 코드를 플레이어 아래에 복사 가능한 텍스트로 제공하고, 성공 응답 장면은 짧은 GIF로 만들어 퀵스타트 페이지에 넣으세요.

빠른 체크리스트

• 일회용 키를 쓰는 샌드박스 계정
• 현실적인 시드 데이터
• 알림 끄기, 셸 히스토리 정리
• 폰트 확대, 윈도우 배치
• 목표 → 인증 → 요청 → 응답 구조
• 정렬된 JSON, 핵심 필드에 줌
• 대기 시간 잘라내기
• 화면에 버전 표시
• 해당 레퍼런스 섹션 옆에 임베드
• 영상과 함께 복사 가능한 코드 게시

레퍼런스 문서는 무엇이 가능한지 알려줍니다. 좋은 녹화는 그것이 실제로 동작함을 보여줍니다. 그리고 보통 그것이 첫 성공 호출까지 개발자를 데려갑니다.