파트너 포털 결제 API 문서 정비로 온보딩 시간 단축

기능이 어느 정도 안정됐다 싶을 때 팀에서 신규 멤버 온보딩을 맡게 됐다. 막상 "이거 보고 따라 해봐요" 하고 줄 만한 문서가 없다는 걸 그때야 실감했음. 구두로 설명하고, 슬랙 스레드 뒤지고, 코드 직접 열어서 설명하는 패턴이 반복됐다. 그게 계기가 됐고, 파트너 포털 쪽 결제 API 문서 전체를 다시 정리했음.

왜 지금 했나

타이밍 이야기를 먼저 하자면, 기능 개발이 마무리되는 시점이 문서 쓰기에 가장 좋은 창이다. 설계 결정이 머릿속에 남아 있고, 코드가 아직 내 손에서 뜨거울 때. 이 시점을 놓치면 코드는 그대로 있는데 맥락이 날아가 버린다.

결제 도메인은 특히 그게 심하다. Pay 쪽 API는 요청 파라미터 하나 잘못 보내면 트랜잭션이 실패하거나, 파트너 포털에서 부정확한 상태로 화면에 뜨는 식으로 증상이 나온다. 에러가 명확하지 않으니 새로 들어온 멤버 입장에선 어디서 뭘 잘못한 건지 추적하기가 굉장히 어렵다. 이런 도메인일수록 "어쨌든 코드 보면 알겠지"로 넘기면 안 된다.

또 하나. API 문서는 개발 팀 내부용이기도 하지만, 파트너 포털의 경우 외부 연동 작업이 생길 때 레퍼런스로 쓰인다. 내부에서만 돌 때는 슬랙으로 커버가 됐지만, 연동 대상이 늘어나는 순간 그 방식은 바로 터진다. 문서를 미리 만들어두지 않으면 그 타이밍에 발목이 잡힌다.

정리한 내용

이번에 정리한 건 크게 두 가지다. API 레퍼런스와 개발 가이드.

API 레퍼런스는 각 엔드포인트를 표 형태로 정리했다. 요청 파라미터, 응답 구조, 가능한 에러 케이스까지 명시했음. 에러 케이스를 특히 공들인 이유가 있는데, 결제 API 특성상 성공 케이스보다 실패 케이스의 종류가 더 많고 각각 핸들링 방식이 다르기 때문이다.

개발 가이드는 로컬 환경 세팅부터 배포까지 순서대로 따라갈 수 있게 작성했음. 여기서 중요한 건 "이 명령어를 실행해라"만 쓰는 게 아니라, 왜 이 단계가 필요한지 짧게라도 적어두는 것이다. 그냥 커맨드 나열이면 뭔가 안 됐을 때 막막해진다.

문서 구조는 아래처럼 잡았다:

docs/
├── README.md          # 전체 개요, 빠른 시작
├── api-reference.md   # 엔드포인트별 명세
├── architecture.md    # 시스템 구조, 주요 컴포넌트 관계
└── dev-guide.md       # 로컬 세팅 - 배포 순서

구조를 이렇게 나눈 데는 이유가 있다. README는 맥락을 모르는 사람이 처음 봐도 5분 안에 "이게 뭔지"를 알 수 있어야 한다. api-reference는 작업 중에 탭을 열어두고 반복 참조하는 용도니까 검색하기 쉽게 편평하게 유지한다. architecture는 처음엔 빠질 것 같지만, 시스템 규모가 커지면 제일 먼저 찾게 되는 문서다. 파트너 포털처럼 외부 연동 포인트가 있는 경우는 특히.

문서화를 하면서 느낀 것

코드를 짤 때는 "나는 알고 있으니까 괜찮다"고 자연스럽게 생각하게 된다. 근데 6개월 뒤에 같은 코드를 보면 낯설어지는 경험을 한 번쯤은 해봤을 거다. 내가 쓴 코드인데 왜 이렇게 짰지, 싶은 순간.

문서화에서 핵심은 '왜'를 기록하는 것이다. '무엇'은 코드를 보면 알 수 있지만, '왜 이렇게 설계했는가'는 코드에서 드러나지 않는다. 결제 쪽에서는 이 부분이 빠지면 나중에 변경할 때 잘못된 방향으로 가기 쉽다. 특정 파라미터가 optional로 설계된 이유가 있을 텐데, 그 이유를 모르면 나중에 required로 바꿨다가 기존 연동이 터지는 식의 사고가 난다.

그리고 좋은 문서는 한 번에 완성되지 않는다. 이번에 처음부터 완벽하게 쓰려고 했으면 아마 시작도 못 했을 거다. 일단 50%짜리를 내놓고, 실제로 온보딩에 쓰면서 막히는 지점을 보완하는 식이 현실적이다. 새로 합류한 멤버가 "이 부분이 불분명했어요" 하는 피드백이 제일 좋은 리뷰어다.

습관 면에서는 API를 바꿀 때 문서도 같이 바꾸는 걸 팀 컨벤션으로 박아두는 게 중요하다. 코드 리뷰에서 "이 변경에 대응하는 문서 업데이트가 있나요?"를 체크하는 것만으로도 문서가 stale해지는 속도를 상당히 늦출 수 있다. 문서는 쓰는 게 어려운 게 아니라, 최신 상태를 유지하는 게 어렵다.

앞으로 API나 복잡한 로직을 새로 만들 때마다 최소한 의사결정 배경은 남겨두려고 한다. 코드 옆에 주석 한 줄이라도, 문서에 단락 하나라도. 그게 쌓이면 팀이 의존할 수 있는 기반이 생긴다.