문서화 작업이 한창 진행되던 어느 날, 기술 작가 중 한 명이 깊은 고민에 빠진 표정으로 입을 열었다.
“우리가 작성하는 문서들을 다시 읽어봤습니다. ‘무엇’이 바뀌었고 ‘어떻게’ 사용하는지에 대해서는 정말 상세하게 설명하고 있어요. 하지만 가장 중요한 질문 하나가 빠져있는 것 같습니다.”
그는 잠시 말을 멈추고 팀원들을 둘러보았다.
“바로 ‘왜 이렇게 바뀌었나요?’ 라는 질문입니다.”
그의 지적은 문서화 팀의 핵심을 관통했다. 그들은 기능의 표면적인 변화를 설명하는 데 집중한 나머지, 그 변화의 이면에 있는 React Core Team의 근본적인 ‘의도’와 ‘철학’을 놓치고 있었다.
“예를 들어, 서버 액션을 봅시다.” 그가 말을 이었다. “우리는 e.preventDefault()가 사라지고 코드가 간결해졌다고 설명합니다. 하지만 ‘왜’ React는 굳이 표준 HTML의 action 속성으로 회귀하는 방식을 택했을까요? 그 결정 뒤에는 ‘점진적 향상’이라는 웹의 오랜 가치를 존중하려는 철학이 숨어 있습니다. 우리는 그 이야기를 하고 있지 않아요.”
그의 말에 로렌 탄은 깊이 공감했다. 그녀는 Next.js 13이 처음 공개되었을 때 커뮤니티가 겪었던 혼란을 떠올렸다. 그 혼란의 가장 큰 원인은 ‘왜’에 대한 설명이 부족했기 때문이었다.
“당신 말이 맞아요.” 로렌이 단호하게 말했다. “우리의 독자는 기계가 아닙니다. 그들은 단순히 API 사용법을 암기하는 것이 아니라, 변화의 맥락을 이해하고 싶어 합니다. 그 맥락을 이해해야만 새로운 멘탈 모델을 진정으로 받아들일 수 있어요.”
그날 회의를 기점으로, 문서화의 방향은 다시 한번 수정되었다. 팀은 모든 주요 기능 페이지에 ‘철학(Philosophy)’ 또는 ‘핵심 개념(Core Concepts)’이라는 이름의 새로운 섹션을 추가하기로 결정했다.
- 서버 컴포넌트 페이지에는: ‘클라이언트가 만능이 아니다’라는 인식에서 출발하여, 서버와 클라이언트의 올바른 역할 분담에 대한 고민을 담았다.
- 동시성 기능 페이지에는: ‘사용자의 시간을 존중한다’는 원칙 아래, 어떻게 UI의 응답성을 최우선으로 고려하게 되었는지를 설명했다.
- Actions 페이지에는: ‘웹 표준으로의 회귀’라는 주제로, 최신 기술과 웹의 기본 원칙이 어떻게 조화를 이룰 수 있는지에 대한 비전을 제시했다.
이 섹션들은 기술적인 설명을 넘어, 한 편의 짧은 에세이와도 같았다. 그 안에는 React Core Team이 내렸던 수많은 결정과, 그 결정들 사이에서 벌어졌던 치열한 토론, 그리고 마침내 도달한 합의의 과정이 녹아들어 있었다.
이러한 변화는 문서화 작업을 훨씬 더 어렵게 만들었다. 기술 작가들은 이제 단순한 정보 전달자를 넘어, React의 철학을 해석하고 전달하는 이야기꾼이 되어야 했다. 그들은 핵심 개발자들과 더 깊은 인터뷰를 진행하며, 그들의 머릿속에 있는 무형의 생각들을 명료한 문장으로 끄집어내는 고된 작업을 이어갔다.
하지만 그들은 이 작업이 반드시 필요함을 알고 있었다.
“왜 이렇게 바뀌었나요?” 라는 커뮤니티의 질문에 답하는 것. 그것은 단순한 친절이 아니었다. 그것은 개발자들을 변화의 동반자로 여기고, 그들의 지적인 호기심을 존중하는 React의 성숙한 태도였다. 이 노력을 통해, React 19의 문서는 단순한 API 레퍼런스를 넘어, 새로운 패러다임의 등장을 알리는 시대의 선언문으로 거듭나고 있었다.
