3개월 전에 팀에 새로운 개발자가 합류했다. 첫 주에 온보딩을 진행하면서 "프로젝트 관련 문서는 Confluence에 있으니까 한번 읽어봐"라고 말했다. 이틀 뒤에 그 개발자가 DM을 보냈다. "Confluence에 문서가 되게 많은데, 어떤 걸 먼저 읽어야 할지 모르겠어요. 그리고 몇 개 읽어봤는데 현재 코드랑 다른 것 같아서요."

마음이 찔렸다. 맞는 말이었다. Confluence에 문서가 200개 넘게 있었지만, 최근 6개월 내에 업데이트된 건 10개도 안 됐다. 나머지는 2년 전 아키텍처를 설명하고 있거나, 이미 삭제된 기능의 스펙이거나, 누군가 "나중에 정리하겠다"고 만들어놓고 제목만 있는 빈 페이지들이었다.

우리 팀의 Confluence는 문서 저장소가 아니라 무덤이었다.

왜 문서는 무덤이 되는가#

원인을 분석해보면 결국 하나로 수렴한다. 문서의 종류를 구분하지 않았다. 모든 문서를 "문서"라는 하나의 카테고리에 넣고, 같은 방식으로 쓰고, 같은 곳에 보관했다. 그러니까 기술 스펙 문서 옆에 회의록이 있고, 온보딩 가이드 옆에 브레인스토밍 메모가 있었다. 찾는 데만 10분이 걸리니까, 차라리 옆 사람한테 물어보는 게 빠르다.

Divio라는 회사에서 만든 문서화 프레임워크가 이 문제를 정확히 짚는다. 핵심 통찰은 이거다. "문서"라는 건 없다. 4가지 종류의 서로 다른 것이 있을 뿐이다.

1. 튜토리얼 (Tutorial) — 학습 중심#

처음 접하는 사람을 위한 가이드. "이 프로젝트에 처음 온 사람이 따라 하면 동작하는 결과를 볼 수 있는 문서." 핵심은 해보는 것이다. 설명보다 행동이 우선이다. "왜 이렇게 하는지"보다 "이렇게 하면 이렇게 된다"에 집중한다.

우리 팀에서 이 카테고리에 해당하는 건 "로컬 개발 환경 세팅 가이드"와 "첫 번째 PR 올리기" 같은 문서다. 새 개발자가 첫날 따라 하면 로컬에서 프로젝트가 돌아가야 한다. 여기서 Docker의 네트워킹 모델을 설명하거나 Webpack 설정의 역사를 서술하면 안 된다. 그냥 pnpm install 치고, pnpm dev 치고, localhost:3000이 뜨면 성공이라는 것만 전달하면 된다.

2. 하우투 가이드 (How-to) — 작업 중심#

특정 작업을 완수하기 위한 레시피. "API 엔드포인트 추가하는 법", "새 컴포넌트를 디자인 시스템에 등록하는 법", "스테이징 환경에 배포하는 법". 튜토리얼과 다른 점은, 이미 기본을 아는 사람이 보는 거다. "이걸 어떻게 하지?"라는 질문에 답하는 문서.

이게 가장 실용적이면서도 가장 잘 안 쓰이는 종류다. 왜냐하면, 이걸 쓸 수 있는 사람은 이미 하는 방법을 알고 있어서 문서로 남길 동기가 약하다. "나는 알고 있으니까 굳이 안 써도 되지 않나?" 근데 이 문서가 없으면, 매번 누군가가 물어볼 때마다 구두로 설명해야 한다. 같은 설명을 3번 이상 하고 있으면, 그건 문서가 없다는 신호다.

3. 레퍼런스 (Reference) — 정보 중심#

API 문서, 컴포넌트 props 목록, 환경 변수 목록, 에러 코드 목록 같은 것. 설명이 아니라 사실의 나열이다. 사전과 같다. 처음부터 끝까지 읽는 게 아니라, 필요할 때 찾아보는 거다.

이건 자동 생성이 가능한 영역이 많다. TypeScript 타입 정의에서 컴포넌트 props 문서를 뽑아내거나, Swagger/OpenAPI에서 API 레퍼런스를 생성하거나. 자동 생성의 좋은 점은 코드와 문서가 동기화된다는 거다. 수동으로 작성한 레퍼런스는 코드가 바뀌면 거짓말이 된다. 그 거짓말 문서가 Confluence 무덤의 주요 거주자다.

4. 설명 (Explanation) — 이해 중심#

"왜 이렇게 했는지"를 다루는 문서. 아키텍처 결정 기록(ADR), 기술 선택의 배경, 특정 패턴을 채택한 이유. 시간이 지나도 가치가 유지되는 유일한 종류의 문서다.

6개월 전에 쓴 "왜 우리가 CSS Modules 대신 Tailwind를 선택했는가" 문서는 지금도 유효하다. Tailwind 버전이 올라가고 설정이 바뀌어도, 선택의 배경은 변하지 않으니까. 새로 온 개발자가 "왜 Tailwind 쓰는 거예요?"라고 물었을 때, 그 문서 링크 하나로 30분짜리 대화를 대체할 수 있다.

3주를 아낀 한 장의 문서#

이 분류를 알기 전에, 우연히 좋은 문서를 하나 쓴 적이 있다. 지금 돌이켜보면 "설명" 카테고리에 해당하는 문서였다.

프로젝트의 인증 플로우가 복잡했다. OAuth + 자체 토큰 + 리프레시 토큰 + 세션 관리가 여러 서비스에 걸쳐 돌아가고 있었다. 코드만 봐서는 전체 흐름이 안 보였다. 시퀀스 다이어그램 없이는 이해가 불가능한 구조. 내가 이걸 파악하는 데 2주가 걸렸다.

2주 동안 삽질한 게 아깝기도 하고, 다시는 이 고통을 겪고 싶지 않아서 문서를 썼다. 인증 플로우의 전체 그림, 각 서비스의 역할, 토큰이 언제 발급되고 언제 갱신되고 언제 만료되는지, edge case(토큰 갱신 중 다른 탭에서 요청이 오면?), 그리고 왜 이런 구조가 됐는지의 히스토리.

3개월 뒤에 그 문서가 빛을 발했다. 새로 합류한 백엔드 개발자가 인증 관련 수정을 해야 했는데, 그 문서를 읽고 하루 만에 전체 플로우를 파악했다. 내가 2주 걸린 걸 하루 만에. 그리고 또 3개월 뒤에 프론트엔드 개발자가 합류했을 때도 같은 일이 벌어졌다. 대략 계산하면, 그 문서 하나가 최소 3주의 시간을 아꼈다. 내가 문서 쓰는 데 든 시간은 반나절이었다.

Julia Evans의 교훈: 복잡한 걸 단순하게#

Julia Evans라는 개발자가 있다. 이 사람은 기술 블로그와 zine(일종의 미니 만화 가이드)으로 유명하다. DNS 동작 원리, 디버깅 기법, 시스템 콜 같은 어려운 주제를 놀라울 정도로 쉽게 설명한다.

Evans의 접근법에서 배울 게 있다. 그는 "지식의 빈틈을 채운다"는 철학을 갖고 있다. 사람들이 실무에서 매일 마주치지만 제대로 설명된 적 없는 것들을 찾아서, 그걸 설명한다. 이론적으로 완벽한 설명이 아니라, 실무자가 "아, 그거 그렇게 되는 거였어?"라고 느끼는 수준의 설명.

이걸 팀 문서에 적용하면 이렇다. 모든 걸 문서화하려고 하면 실패한다. 대신, 팀에서 같은 질문이 반복되는 것을 관찰한다. "스테이징 배포는 어떻게 해요?" "이 API의 에러 코드가 뭐뭐 있어요?" "이 컴포넌트는 언제 쓰는 거예요?" 이런 질문이 3번 이상 나오면, 거기에 문서가 필요하다는 뜻이다.

Evans처럼 복잡한 걸 단순하게 만드는 핵심은 독자를 명확히 하는 것이다. "이 문서를 읽는 사람은 누구인가? 그 사람이 이미 알고 있는 것은 뭔가? 이 문서를 읽고 나서 할 수 있어야 하는 것은 뭔가?" 이 세 가지만 정하면, 문서의 범위와 깊이가 자연스럽게 결정된다.

문서를 쓰는 건 이기적인 행위다#

사실, 내가 문서를 쓰는 가장 큰 동기는 이타심이 아니다. 이기심이다.

미래의 내가 첫 번째 독자다. 6개월 뒤의 나는 지금 작성한 코드의 맥락을 다 까먹는다. 이건 확실하다. 왜 이 라이브러리를 골랐는지, 왜 이 아키텍처를 택했는지, 왜 이 워크어라운드를 넣었는지. 코드에 주석을 달아도 한계가 있다. 주석은 "무엇을"은 설명하지만 "왜"를 설명하기 어렵다. "왜"를 담는 건 문서의 영역이다.

설명하면 이해가 깊어진다. 뭔가를 문서로 정리하다 보면, 내가 제대로 이해하지 못한 부분이 드러난다. "이 부분은... 음... 그냥 이렇게 되는 건데..." 이런 순간이 오면, 그건 내 이해에 구멍이 있다는 뜻이다. 문서를 쓰기 위해 그 구멍을 채우는 과정이, 결국 나의 역량을 높이는 과정이다.

질문을 비동기로 처리할 수 있다. "이거 어떻게 해요?"라는 DM이 올 때마다 15분씩 설명하는 대신, 문서 링크를 보내면 된다. 15분이라는 시간도 시간이지만, 더 큰 문제는 컨텍스트 스위칭이다. 집중해서 코드를 짜고 있는데 질문이 오면, 답변을 하고 다시 원래 작업으로 돌아오는 데 추가 시간이 든다. 문서가 있으면 이 비용이 사라진다.

Confluence 무덤을 살리는 법#

팀의 문서 문화를 한 번에 바꾸기는 어렵다. 근데 몇 가지를 실천하면서 조금씩 나아졌다.

만료일을 정한다. 모든 문서에 "이 문서의 유효 기간"을 명시한다. 6개월이면 6개월, 1년이면 1년. 유효 기간이 지나면 리뷰하고, 여전히 유효하면 기간을 연장하고, 아니면 아카이브한다. 이것만으로도 무덤화를 상당히 막을 수 있다.

문서를 코드 리뷰에 포함시킨다. 새로운 기능의 PR에 관련 문서 업데이트가 포함되어 있는지 확인한다. PR 템플릿에 "관련 문서 업데이트 여부" 체크리스트를 넣었다. 처음엔 귀찮다고 했지만, 3개월 지나니까 습관이 됐다.

검색 가능하게 만든다. 문서가 100개여도 찾을 수 있으면 괜찮다. 일관된 제목 규칙, 태그, 분류 체계를 잡는다. Divio 프레임워크대로 "튜토리얼", "하우투", "레퍼런스", "설명" 네 폴더로 나누는 것만으로도 체감이 달라진다.

작게 시작한다. 전체 프로젝트를 문서화하겠다는 야심찬 계획은 실패한다. 대신, 이번 주에 내가 3번 이상 구두로 설명한 것 하나를 문서로 만든다. 다음 주에 또 하나. 한 달이면 4개, 1년이면 50개가 된다. 그 50개가 팀의 운영 방식을 바꾼다.

아무도 안 읽는 문서#

그래도 현실적으로, 아무도 안 읽는 문서가 있다. 공들여 쓴 아키텍처 문서를 올렸는데 리액션이 0개인 경험. "다들 바쁘니까 나중에 읽겠지"라고 스스로 위안했지만, 3개월이 지나도 조회수가 5다. 그중 3은 내가 들어간 거다.

이런 경험이 반복되면 문서 쓰는 의욕이 떨어지는 게 당연하다. 근데 중요한 건, 그 문서가 필요한 순간은 예측할 수 없다는 거다. 장애가 터졌을 때, 새 팀원이 왔을 때, 6개월 뒤에 "이거 왜 이렇게 되어 있지?" 하는 순간에 그 문서가 빛난다. 평소에는 잠자고 있지만, 필요할 때 깨어나는 보험 같은 거다.

그래서 나는 아무도 안 읽을 거라는 걸 알면서도 문서를 쓴다. 미래의 나를 위해, 아직 합류하지 않은 팀원을 위해, 새벽 3시에 장애가 터졌을 때 당황하지 않기 위해. 그리고 한 가지 더, 글로 정리하는 과정에서 내 생각이 명확해지기 때문에.

아무도 안 읽는 문서라도, 쓰는 행위 자체가 가치 있다. 근데 솔직히, 누가 읽으면 더 좋긴 하다.