3. 우리 팀의 문서화는 왜 실패할까? (1)

커머스 도메인과 서버 챕터에서 문서화를 맡은 두 사람은 정책·용어를 찾기 어렵고, 코드의 배경이나 해결 지식이 개인에게 흩어져 협업과 온보딩이 느려지는 문제를 발견했습니다. 구성원 인터뷰를 통해 필요한 문서의 종류뿐 아니라 작성 범위와 정확성에 대한 불확실성, 문서화가 개인의 의지와 추가 책임에 기대는 구조도 확인했습니다. 한쪽은 도메인 지식과 개발자센터 문서 시스템을, 다른 쪽은 전사 문서 시스템 ‘토독’과 서버 챕터 문서화 길드를 운영하며 지식을 모으고 문서 기준·리뷰·자동화를 다루고 있습니다. 문서화를 지속하려면 의지를 독려하는 데 그치지 않고, 흩어진 지식을 한곳에 모으며 작성과 업데이트를 업무 과정에 자연스럽게 연결해야 한다는 점을 배웠습니다.

• 문서화 인터뷰에서는 구성원의 의지보다 어떤 지식이 부족하고 업무에서 어디가 막히는지부터 확인하세요.
• 문서 작성자가 범위와 정확성에 확신을 갖기 어렵다면, 기준과 리뷰 과정을 마련해 공유 부담을 낮출 수 있습니다.
• 문서가 개인의 결심에만 의존하면 바쁜 시기에 밀리므로, 작성과 업데이트를 기존 업무 흐름에 포함해야 합니다.
• 도메인 문서는 정책·용어처럼 제품 맥락을, 챕터 문서는 컨벤션·도구 사용법처럼 직군 공통 지식을 다루는 데 초점을 둡니다.