[ ⚠️ ]
이 문서는 토스 메이커스 컨퍼런스 2025 세션 중 토스의 기가막힌 문서 시스템: 실패에서 배운 교훈들 세션을 정리한 것입니다.
문제의 시작점: "이거 누구한테 물어봐야 하나요?"
토스 프론트엔드팀이 직면했던 가장 큰 문제는 단순했고, 사실 직장인이라면 누구나 겪어보았을 문제였습니다.
새로운 개발자가 입사하면 항상 같은 질문들이 반복되었죠:
- "이 기능은 어떻게 동작하나요?"
- "이 코드는 왜 이렇게 작성했나요?"
- "이 문서가 최신 버전 맞나요?"
- "이건 누가 잘 아시나요?"
Notion, Logseq, Confluence...
여러 도구를 써봤지만 결국 개발자들이 가장 선호하는 방법은 결국 아래와 같았죠.
(옆자리 동료에게) "저기 혹시.. 이거 아세요?"
(슬랙으로) "OO님 이거 써보셨어요?"
네, 결국 수많은 개발자들은 그냥 옆자리 동료에게 물어보는 걸 선호했습니다.
암묵지: 아는 사람만 아는 정보
setTimeout(() => {
someUpdateUI();
}, 0);이런 코드를 보고 "왜 setTimeout을 0으로 설정한거지?"라고 물으면
"아, 그거요? 예전에 IE에서 렌더링 이슈가 있어서..."
이런 대답은 보통 문서에 잘 나와있지 않은 경우가 많죠.
특히 이슈로 인해 급하게 수정된 코드가 문서화에서 누락되는건 흔하게 발생하는 휴먼 에러니까요.
조직이 커질수록 이런 암묵지는 점점 더 큰 문제가 됩니다:
- 담당자가 휴가나 퇴사를 하면 정보가 사라짐
이거 할줄 아는거 OO님인데 지금 장기휴가 중이라서...
- 슬랙은 너무 빠르게 흘러가서 정보를 찾기 어려움 (
게다가 검색은 또 왜 이모양이야) - 질문하기 눈치 보이는 문화가 생김
이런거 물어봐도 되나..? 나 너무 멍청해보이는거 아니야..?
이전의 문서화 시도들이 실패했던 이유
해당 세션 내에서 정확히 언급해 주시지는 않았지만, 추정컨데 아무래도 아래와 같은 이유가 아니었을까 싶습니다.
- 문서가 다양한 매체에 분산되어 있어서, 찾기 어려움
- 문서의
Ownership이 명확하지 않아서, 누가 문서를 관리하는지 모호함 - 이로인해 방치되고, 최신화되지 않는 문서가 쌓임
- 결국 찾기 힘든 정보, 불확실한 정보가 된 문서더미..
이러한 현실은 사실 수많은 개발자들이 겪어본, 그리고 겪고있는 문제죠.
이러한 이유로 개발자들은 여전히 옆자리 동료에게 물어보는 걸 선호한게 아닐까 싶습니다.
해결을 위한 두 가지 원칙
토스는 문서관리를 위한 두 가지 핵심 원칙을 세웠다고 합니다. 세션 중에서도 특히나 공감되는 내용이었어요.
1. 신뢰할 수 있는 정보
- 최신 상태 유지
- 정확성 보장
- 자기 완결성 (다른 문서 참조 최소화)
- 충분한 커버리지 (최소 85% 이상 궁금증이 해소되어야 한다!)
2. 누구나 접근 가능
- 통합 검색: 알골리아 활용, 누구나 쉽게 도달 가능
- 워크플로우 통합:
박씨(토스 내부 슬랙 봇) 도입으로, 기존 업무환경(슬랙)을 벗어나지 않고 문서에 접근 가능 - 컨텍스트 스위칭 최소화: MCP 활용 (
IDE를 벗어나지 않겠다는 의지)
실질적 해결책: '박씨' 봇과 통합 문서 시스템
박씨 봇
- 토스 내부 슬랙 봇, 아티클 참조
- 문서 검색 기능 제공
- 인사이트
- 접근성이 생각보다 훨씬 중요하다.
- 개발자들이 문서를 두고 결국 옆사람에게 물어보는것도, 본질적으로는 접근성 때문이다. 고품질의 문서라도 보려면 일일이 플랫폼에 들어가서 찾고, 검색해야 한다.
박씨 봇의 예상치 못한 효과
-
질문의 허들이 극적으로 낮아짐
- 사람이 아니니까 "이런 걸 물어봐도 되나?" 고민이 사라짐
- 새벽 3시에도, 점심시간에도 눈치 볼 필요 없음
- "멍청한 질문"이라는 개념 자체가 없어짐
-
커뮤니티 지식의 활성화
- 박씨가 모르는 내용은 답을 아는 누군가가 등장해서 답변해주는 경우가 생김
- 다른 개발자들의 답변이나 외부자료가 있다면 그것도 박씨의 학습 데이터로 즉시 활용 가능함(
!학습커맨드) - 질문하는 사람 + 답하는 사람 + 미래에 같은 궁금증을 가질 사람 모두에게 도움이 됨!
통합 문서 시스템
문서 시스템의 핵심 요소
- 통합 검색
- 전체 플랫폼에 대한 통합 검색의 중요성 또한 생각보다 크다
- 익숙한 플랫폼
- 문서를 찾기위해 새로운 플랫폼으로 전환하거나, 새로운 도구를 사용하는 것은 부담스럽다.
- 컨텍스트 스위칭 최소화
- 문서를 찾기위해 IDE 밖으로 벗어나는 것 조차 일종의 벽이 된다.
- (+@) 피드백 시스템
- 단순한 '좋아요' 등 피드백도 양질의 문서 수렴을 위해 도움이 된다.
문서 생성 파이프라인
- 코드 기반 자동 문서 생성 (
JSDoc) - CI 통합 (문서 없으면 머지 불가)
- 기술 리뷰 (수석 개발자)
- Technical Writer 리뷰 (가독성)
- 자동 신선도 체크 (오래된 문서 알림)
실제 구현 예시: Docflow
// 예시: JSDoc을 활용한 자동 문서화
/**
* @description 사용자 주문 내역을 조회합니다
* @param {string} userId - 사용자 ID
* @returns {Promise<Order[]>} 주문 목록
* @throws {UserNotFoundError} 사용자를 찾을 수 없을 때
* @example
* const orders = await getUserOrders('user123');
*/
export async function getUserOrders(userId: string): Promise<Order[]> {
// 구현...
}문화 만들기: 문서화는 인프라다
세션의 결론으로 말씀하신 내용이 바로, 문서야 말로 회사의 인프라라는 것이었습니다.
매우 중요한 내용이라고 생각합니다.
문서화 활성화 전략: 선순환 구조 만들기!
가장 중요한 것은 "읽기" 단계라고 합니다. 아무리 좋은 문서도 읽히지 않으면 의미가 없으니까요.
"읽어야 뭐라도 한다" - 토스는 이 단계에 집중했습니다.
문서화 활성화 구체적인 전략들
- 리더들의 마중물 역할
- 팀 리더들이 먼저 초안을 대량으로 작성
- "완벽하지 않아도 괜찮다, 일단 쓰자"는 분위기 조성
- 주 1회 "문서화 데이" 운영
- 정복단 활동
- 특정 기술이나 도메인을 깊게 파고드는 스터디 그룹
- 스터디 결과물을 반드시 문서화하는 규칙(?)
- 문서화 세션
Technical Writer가 진행하는 글쓰기 교육- 개발자를 위한 기술 문서 작성법
- 좋은 문서/나쁜 문서 사례 분석
문서의 종류별 관리 전략
-
레퍼런스 문서
- 특징: 특정 소스코드에 대한 설명, 사전과 같은 속성
- 관리 방법:
JSDoc+Docflow를 통한 자동화 - 품질 보증:
CI통합으로 문서 없으면 코드도 머지 불가
-
가이드 문서
- 특징: 튜토리얼, How-to, 개념 설명
- 관리 방법: 기술 리뷰 + Technical Writer 리뷰
- 품질 보증: 정기적인 신선도 체크, 피드백 반영
핵심 교훈: 문서 시스템 구축의 정석
1. 문서는 조직의 인프라다
- 문서를 단순한 '기록'이 아닌 '인프라'로 인식하는 관점의 전환이 필요합니다.
- 도로나 전기처럼, 문서도 조직이 원활하게 돌아가기 위한 필수 인프라입니다.
2. 접근성이 신뢰성만큼 중요하다
- 아무리 정확하고 최신의 문서라도, 찾기 어렵거나 접근이 불편하면 무용지물입니다.
- "물어보기"만큼 쉬운 접근성을 제공해야 합니다.
3. 시스템과 문화, 둘 다 필요하다
- 시스템: 자동화, 통합 검색, 봇
- 문화: 문서화 습관, 피드백 문화, 지속적 개선
4. 80/20 법칙을 기억하라
- 모든 것을 100% 문서화할 필요는 없습니다.
- 하지만 자주 필요한 정보의 80% 이상은 반드시 고품질로 유지해야 합니다.
마무리
사실, 개인적으로 이번 컨퍼런스에서 기술적인 내용들보다도 더 공감되고, 앞으로 도움이 될 내용들이 많았던 것 같습니다.
지금 회사에서도 문서화와 정보 검색 등에 대한 문제를 해결하기 위해 노력하고 있는데, 이번 세션을 통해 많은 것을 배워 적용 해 볼 수 있을 것 같습니다.
읽어주셔서 감사하고, 도달할 수 있을지는 모르겠지만, 오늘 발표해주신 연사분들께 다시 한 번 감사드립니다!
