개발을 하다 보면 누구나 문서에 대한 불만을 한 번쯤 경험합니다. 제품은 빠르게 발전하지만 문서는 그 속도를 따라가지 못하고, 어느 순간 팀 내부에서도 “우리 문서, 솔직히 아쉽다”라는 말이 자연스럽게 나오게 되죠. 노티플라이 팀도 같은 문제로 고민하고 있었습니다.

노티플라이 팀은 100개가 넘는 고객사가 신뢰하는 통합 메시징 자동화 CRM 솔루션으로, 성장하는 팀들이 모든 채널에서 고객 커뮤니케이션을 보다 매끄럽게 관리할 수 있도록 돕고 있습니다. 이들은 이미 도큐사우르스 기반의 문서 시스템을 가지고 있었지만, 문서 대부분이 정적인 페이지로 되어 있어 전체적인 구조나 UX가 만족스럽지 않았고 새로운 제품을 소개하기에도, 외부 고객에게 안내하기에도 아쉬움이 컸죠.

우리가 노티플라이 팀과 처음 이야기할 때 가장 먼저 강조한 점은 자일로닥스로의 플랫폼 이동이 아니라 문서의 구조와 정보의 품질이라는 점이었습니다. 자일로닥스를 쓰느냐보다 더 중요한 것은 문서가 얼마나 “잘 읽히는가”였기 때문입니다.

잘 읽히는 문서란, 구조가 명확하고 정보가 논리적으로 배열되어 있으며, 실제 사용자가 이해하기 쉬운 형태로 제공되는 문서입니다. 그래서 우리는 문서를 다시 살펴보는 방식으로 접근했고 플랫폼은 이미 시중에 좋은 것들이 많아 그 중 다양한 UI 컴포넌트를 제공하는 Mintlify 플랫폼을 제안했습니다. 이미 노티플라이 측에서 써본 경험이 있다는 것도 선택하는 데 중요한 요소였습니다.

노티플라이의 개발자 문서의 주요 독자는 한국 개발자였기 때문에, 엔드포인트별 제목과 설명을 한국어로 풀어쓰고, 기능적 속성이 아니라 주제별로 그룹화해 문서의 이해도를 크게 높였습니다. 단순히 번역이 아니라, 개발자 입장에서 실제로 읽고 이해하기 좋은 표현으로 재작성한 것도 중요한 변화였습니다.

인상적인 부분은 실제 노티플라이의 개발자 문서를 살펴봤던 개발자와 인터뷰 중에 ‘API를 실제로 서비스에 붙이고 나서야 이 서비스를 대략적으로 이해할 수 있었다’라는 부분이었습니다. 자일로시스템즈는 이 부분을 너무 해결하고 싶었습니다.

가장 핵심적인 작업은 기존 API 문서를 모두 OpenAPI 기반으로 완전히 재구성하는 일이었습니다. MDX 파일로 API 문서를 관리하는 방식은 시간이 지날수록 관리 난이도가 높아지고, 내용의 통일성도 점점 흐트러집니다. 우리는 SDK 문서를 제외한 모든 API 문서를 OpenAPI 스펙으로 이전했으며, 반복적으로 등장하는 error 스키마와 security 스키마, 그리고 요청과 응답 스키마를 공통 컴포넌트로 통합했습니다. 최종적으로 약 10개 이상의 MDX 파일을 제거하고 단 하나의 OpenAPI 파일로 모든 API 문서를 관리할 수 있는 구조를 만들었습니다. 그 결과 전체 스펙은 약 2,800줄 규모로 정리할 수 있었습니다.

OpenAPI 기반으로 문서를 정리한 것은 Mintlify의 다양한 기능을 활용하는 데도 큰 도움이 되었습니다. Mintlify가 제공하는 UI 컴포넌트를 최대한 활용하기 위해 필요한 x-mint 확장 기능을 적극적으로 적용했습니다. 이를 통해 각 엔드포인트의 이름, 설명 등을 Mintlify가 호스팅하는 페이지에 자연스럽게 표현할 수 있었습니다.

또한 그룹 구조, example 데이터를 스펙 내부에서 자연스럽게 표현했고, docs.json과 연동하여 Mintlify의 고급 테마와 컴포넌트도 이용했습니다. 특히 OpenAPI에 기록된 example들은 Playground 기능을 통해 자동으로 표시되며 개발자가 훨씬 직관적으로 API를 이해할 수 있는 경험을 제공했습니다.

물론 모든 객체의 example이 Playground에서 완벽하게 표현되는 것은 아니었습니다. 요청 및 응답 구조가 복잡할수록 Playground에서 동적으로 렌더링하기 어려웠습니다. 이 과정에서 많은 시간을 썼습니다. 그래서 우리는 가장 핵심적인 객체들만 Playground에서 시각적으로 제공하고, 나머지는 Mintlify의 Callout 컴포넌트를 활용해 주요 포인트를 강조하는 방식으로 해결했습니다. 이렇게 함으로써 문서 소비자가 테스트하는 데 문제 없는 환경을 제공했고 필요한 정보는 빠르게 파악하며, 복잡한 흐름은 시각적으로 정돈된 방식으로 이해할 수 있도록 설계했습니다.

작업 과정에서 인상적이었던 점은 노티플라이 팀이 처음에는 단순히 “기존 문서를 조금 옮기고 보완하는 수준”을 기대했던 반면, 실제로는 문서 전체 흐름이 완전히 새롭게 탄생한 경험을 하게 되었다는 점이었습니다. 우리는 문서를 “시작하는 법 → 인증 방식 → 주요 API → 예제 → 에러 핸들링”이라는 자연스럽고 읽기 좋은 서사 구조로 재구성했습니다. 이는 기존처럼 기능 중심으로 단편적으로 쌓여 있던 문서와는 완전히 다른 접근 방식이었고, 노티플라이 팀 내부에서도 “이제 외부 사용자에게도 자신 있게 문서를 보여줄 수 있다”는 반응이 자연스럽게 나왔습니다.

특히 변경된 왼쪽 네비게이션 구조는 팀원들에게 가장 큰 만족을 줬습니다. 이전에는 기능 단위로 조각조각 나뉘어 있던 문서가 이제는 논리적으로 잘 묶인 카테고리로 정리되면서, 문서를 보는 순간 전체 구조가 어떻게 연결되는지 한눈에 파악할 수 있게 되었기 때문입니다. 또한 Mintlify 플랫폼에 대한 우리 팀의 깊은 이해도를 바탕으로, 노티플라이 팀이 기존에는 사용하지 못했던 다양한 컴포넌트와 기능을 문서 전체에 녹여냈고, 그 결과 문서의 표현력과 전달력이 대폭 향상되었습니다.

결과적으로 노티플라이 팀은 당초 계획보다 훨씬 여유 있게 잡았던 문서 작업 일정을 오히려 앞당기게 되었습니다. “더 빨리 고객에게 보여주고 싶다”는 의견이 나올 정도로 만족도가 높았고, 현재 노티플라이의 공식 문서는 이미 새 구조로 전면 교체된 상태입니다. 문서 경험이 달라지니 내부 구성원뿐 아니라 외부 사용자에게도 더 신뢰감 있는 인상을 줄 수 있었고, 이는 곧 제품 자체의 완성도를 높이는 효과로 이어졌습니다.

문서가 아쉬운 순간은 팀의 역량 부족 때문이 아닙니다. 대부분의 경우, 구조를 제때 잘 잡아주는 노력과 읽는 사람을 이해하는 전문가가 없었기 때문입니다. 자일로시스템즈는 단순히 예쁜 문서로 이관하는 것이 아니라, 장기적인 확장성을 고려한 “잘 읽히는 문서”를 설계하는 팀입니다. 앞으로도 노티플라이 팀처럼 문서를 통해 고객 경험을 개선하고 싶은 팀과 더 많은 성공 사례를 만들어갈 예정입니다. 문서에 대한 고민이 있다면 언제든 편히 연락주시 바랍니다.

nick@zylosystems.com