릴리스를 나흘 앞두고, React Core Team의 개발자들은 비교적 차분한 상태를 유지하고 있었다. 코드는 동결되었고, 남은 것은 사소한 버그 리포트를 모니터링하는 것뿐이었다. 하지만 문서화 팀의 사무실은 그야말로 전쟁터였다.
“이 예제 코드, useFormState의 초기 상태가 null이면 타입 에러가 발생할 수 있습니다. initialState 객체의 구조를 명확히 정의해야 해요.”
“서버 컴포넌트와 SSR의 차이점을 설명하는 비유가 너무 길어요. 더 간결하게 다듬어야 합니다.”
“업그레이드 가이드에서 이 부분은 잠재적인 호환성 문제를 너무 가볍게 다루고 있는 것 같습니다. 더 강하게 경고해야 합니다.”
기술 작가들과 개발자들은 마지막 리뷰 세션에서 한 문장, 한 단어를 놓고 치열한 토론을 벌이고 있었다. 세상에서 가장 뛰어난 기능도, 그 설명서가 엉망이면 아무도 제대로 쓸 수 없다는 사실을 그들은 너무나 잘 알고 있었다.
이번 문서화 작업의 최종 목표는 단순히 ‘정확성’을 넘어, ‘공감’을 이끌어내는 것이었다.
로렌 탄은 문서화 팀 전체에 다시 한번 방향성을 강조했다.
“우리의 독자가 누구인지 잊지 맙시다. 그들은 수년간 React 18의 방식으로 생각해 온 개발자들입니다. 그들에게 갑자기 ‘이제부터는 이렇게 하세요’라고 명령해서는 안 됩니다. 그들의 기존 지식을 존중하고, 그 위에서 새로운 개념을 차근차근 쌓아 올릴 수 있도록 도와야 합니다.”
이 원칙에 따라, 팀은 문서의 모든 부분에서 ‘어떻게(How)’가 아닌 ‘왜(Why)’에 초점을 맞추는 데 마지막 힘을 쏟았다.
- API 레퍼런스 페이지: 단순히 함수의 시그니처와 파라미터를 나열하는 대신, ‘이 훅은 어떤 문제를 해결하기 위해 만들어졌는가?’라는 섹션을 최상단에 배치했다.
- 튜토리얼: 코드 블록 사이에 “여기서
startTransition을 사용하는 이유는, 검색 결과 업데이트가 사용자의 타이핑을 방해해서는 안 되기 때문입니다.” 와 같은 ‘의도’를 설명하는 문장을 추가했다. - 핵심 개념 페이지: ‘위치’, ‘시간’, ‘데이터 흐름’이라는 세 가지 멘탈 모델을 중심으로, 모든 기능이 어떻게 유기적으로 연결되는지를 설명하는 다이어그램과 설명을 보강했다.
가장 큰 논쟁 중 하나는 ‘서버 컴포넌트’라는 용어 자체에 대한 것이었다. 일부에서는 이 용어가 개발자들에게 서버 개발에 대한 부담감을 줄 수 있으니, 더 친근한 이름으로 바꾸자는 의견도 있었다. 하지만 팀은 결국 원래의 이름을 유지하기로 결정했다.
“이름이 주는 약간의 부담감은 오히려 좋습니다.” 앤드류가 결론 내렸다. “그것은 개발자에게 이 컴포넌트가 실행되는 ‘환경’이 근본적으로 다르다는 사실을 명확히 인지시키는 역할을 할 겁니다. 명확성이 모호함보다 중요합니다.”
밤이 깊어지고 있었지만, 문서화 팀의 키보드 소리는 멈추지 않았다. 그들은 지금 코드 없는 전쟁을 치르고 있었다. 전 세계 수백만 개발자들이 React 19라는 새로운 세계로 들어서는 첫 관문. 그 관문을 혼란이 아닌 깨달음으로, 좌절이 아닌 희망으로 채우기 위한 마지막 사투였다. 이 보이지 않는 전쟁의 승패에 React 19의 미래가 달려 있었다.
