React 19의 기능 개발이 막바지에 다다르면서, 팀 앞에는 코드만큼이나 중요한 또 하나의 거대한 산이 나타났다. 바로 ‘문서화(Documentation)’였다.
세상에서 가장 혁신적인 기술도, 그것을 사용하는 방법을 아무도 모른다면 무용지물이었다. 특히 React 19처럼 기존의 멘탈 모델을 뒤흔드는 거대한 패러다임 변화에 있어서, 문서의 역할은 절대적이었다.
문서화 팀을 이끌게 된 로렌 탄은 첫 회의에서 팀의 목표를 명확히 했다.
“우리의 목표는 단순히 새로운 API의 사용법을 나열하는 것이 아닙니다. 우리는 개발자들이 React 19의 ‘철학’을 이해하고, 새로운 멘탈 모델을 자연스럽게 습득하도록 이끌어야 합니다.”
그녀의 말처럼, 이번 문서화 작업은 이전과는 완전히 다른 접근이 필요했다.
과거의 문서는 각 기능(useState, useEffect 등)을 독립적인 레고 블록처럼 설명하는 데 중점을 두었다. 하지만 React 19의 기능들은 서로 유기적으로 얽혀 있었기 때문에, 그런 방식으로는 전체 그림을 보여줄 수 없었다.
문서화 팀의 첫 번째 작업은, 거대한 정보의 구조를 설계하는 것이었다.
“‘서버 컴포넌트’ 페이지를 만든다고 가정해봅시다.” 한 기술 작가(technical writer)가 말했다. “이 페이지는 단순히 서버 컴포넌트의 문법만 설명해서는 안 됩니다. ‘왜 서버 컴포넌트가 필요했는가?’라는 질문에서 시작해서, 번들 사이즈 문제, 데이터 페칭의 비효율성을 먼저 언급해야 합니다. 그리고 서버 컴포넌트가 그 문제들을 어떻게 해결하는지를 보여준 뒤에야, 구체적인 사용법으로 넘어가야 합니다.”
그의 의견은 팀의 방향성이 되었다. 모든 문서는 ‘Why(왜)’에서 시작하여, ‘What(무엇)’을 설명하고, ‘How(어떻게)’로 마무리되는 서사 구조를 가져야 했다.
두 번째 과제는 ‘예제 코드’였다. 예제는 단순한 문법 시연이 아니어야 했다. 개발자들이 실제 업무에서 마주할 법한 현실적인 문제 상황을 담고 있어야 했다.
- Before/After: 기존 방식의 문제점을 보여주는 코드와 React 19 방식으로 해결한 코드를 나란히 비교하여, 변화의 가치를 즉각적으로 느끼게 한다.
- 단계별 튜토리얼: 간단한 정적 페이지에서 시작하여, 점진적으로 클라이언트 상호작용, 데이터 로딩, 폼 제출 기능을 추가해가며 React 19의 핵심 개념들을 자연스럽게 익힐 수 있는 학습 경로를 제공한다.
- 주석의 활용: 코드 한 줄 한 줄에 “이 코드는 서버에서 실행됩니다”, “이 훅은 폼의 제출 상태를 감지합니다”와 같은 친절한 주석을 달아, 코드의 의도를 명확히 전달한다.
문서화 작업은 끝이 보이지 않는 여정이었다. 수백 페이지에 달하는 내용을 작성하고, 수십 개의 예제 코드를 만들며, 모든 설명이 기술적으로 정확한지 핵심 개발자들과 끊임없이 리뷰를 주고받았다.
팀원들은 때로는 지쳐갔지만, 그들의 손끝에서 탄생하는 문서가 앞으로 수백만 명의 개발자들에게 새로운 시대의 등대가 되어줄 것이라는 사명감으로 다시 키보드를 잡았다.
이것은 단순한 사용 설명서를 만드는 작업이 아니었다. React Core Team이 지난 몇 년간 겪었던 고뇌와 발견의 여정을, 전 세계 개발자들을 위한 한 편의 서사시로 재구성하는 위대한 번역 작업이었다. 그들의 노력 없이는, React 19의 혁신은 결코 완성될 수 없었다.
