Read Original
#Backend

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

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

Summary

'문서화 합시다'가 매번 실패하는 진짜 이유를 찾았습니다

토스 개발자들이 의지가 아닌 시스템으로 문서화 난제를 해결한 방법

조직에서 누구나 말하지만 정작 실행은 어려운 문서화의 실패 원인을 기술적, 문화적 관점에서 심층 분석했습니다. 목적 조직과 기능 조직 각각의 특성에 맞는 맞춤형 전략과 AI 챗봇을 활용한 지식 순환 구조를 통해 지속 가능한 문서화의 실마리를 제공합니다.

  • 01목적 조직과 기능 조직의 각기 다른 문서화 니즈와 접근 방식
  • 02개발자의 심리적 허들인 '작성 동기'와 '정확성' 문제 해결
  • 03테크니컬 라이팅 리뷰가 개발자 경험(DX)과 문서 퀄리티에 미치는 영향
  • 04AI 챗봇 답변 정확도 향상을 통한 문서의 실질적 효용 입증
  • 05개인의 의지에 기대지 않는 업무 프로세스 기반의 문서화 구축

RECOMMENDATION

문서 파편화로 협업 병목을 겪고 있거나 지식 공유 문화를 정착시키고 싶은 팀 리드 및 엔지니어에게 실질적인 가이드로 추천합니다.

The Problem

조직 내 문서화가 지속되지 않는 이유는 명확한 작성 기준의 부재, 지식의 정확성에 대한 작성자의 심리적 불안감, 그리고 문서화가 개인의 의지에만 의존하는 부수적인 업무로 인식되는 구조적 한계 때문이다. 파편화된 정보는 협업 시 정보 탐색 비용을 증가시키고 온보딩 효율을 저하시키는 결과를 낳는다.

The Solution

도메인과 챕터의 조직적 특성에 맞춘 인터뷰로 지식 공백을 파악하고, '토독(todoc)' 시스템과 AI 챗봇을 연동하여 문서 활용의 효용성을 높였다. 또한 테크니컬 라이팅 전문가의 리뷰 프로세스를 도입하여 작성 부담을 완화하고 문서 품질을 상향 평준화했다.

The Result

문서 리뷰를 통한 지식 신뢰도 확보로 개발자 만족도가 높아졌으며, 보강된 문서를 바탕으로 AI 챗봇의 답변 품질이 개선되어 구성원들이 문서화의 실질적 가치를 체감하게 되었다. 과거의 파편화된 메신저 히스토리를 뒤지는 시간이 단축되는 성과를 거두었다.

Trade-off

문서화는 본질적으로 미래를 위한 투자이기에 바쁜 실무 환경에서 여전히 우선순위가 밀릴 수 있으며, 작성자가 지속적으로 정보를 업데이트해야 하는 유지보수 책임이 뒤따른다. 시스템적 자동화에도 불구하고 여전히 최소한의 기록 의지가 필요하다는 한계가 있다.

03

Key Concepts

Concept · 01

Technical Writing

기술적인 지식을 독자가 이해하기 쉬운 형태로 구조화하고 명확하게 전달하는 전문적인 글쓰기 기법입니다.

  • 개발자 문서의 품질을 보장하고 심리적 작성 부담을 완화하는 역할
  • 전사 문서화 가이드라인 수립 및 리뷰 프로세스 운영
Concept · 02

Knowledge System

파편화된 정보를 체계적으로 통합 관리하여 누구나 쉽게 검색하고 활용할 수 있도록 돕는 디지털 지식 베이스입니다.

  • 토스 전용 문서 시스템 'todoc'을 활용한 지식 중앙 집중화
  • AI 챗봇 학습 데이터로서의 고품질 문서 관리
Concept · 03

Chapter vs Domain

직군별 전문성을 공유하는 기능 조직(Chapter)과 제품 목표를 향해 모인 목적 조직(Domain)의 구분입니다.

  • 도메인 조직에서는 정책 및 용어 중심의 비즈니스 지식 관리
  • 챕터 조직에서는 기술 표준 및 컨벤션 중심의 직군 공통 지식 관리