Read Original
#Backend

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

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

Summary

'쓰라는 결심'보다 '흐르는 구조'를, 토스가 문서를 대하는 특별한 방식

지식 공유의 공포를 없애고 AI로 문서화 현황을 추적하는 실무 전략

이 아티클은 문서화의 실패를 개인의 의지 문제가 아닌 구조적 문제로 접근하며, 토스 서버 챕터와 커머스 도메인이 겪은 시행착오를 담고 있습니다. AI를 활용해 문서화의 허들을 낮추고 지식 공유를 자동화하는 구체적인 사례를 통해 지속 가능한 문서화 환경을 제안합니다.

  • 01'지식이 틀릴까 봐' 하는 심리적 공포를 해결하는 문화적 접근
  • 02AI 챗봇을 활용한 능동적인 질문 유도 및 지식 전파 전략
  • 03문서화 현황을 수치로 관리하는 AI 기반 모니터링 시스템
  • 04인간 독자와 AI 독자를 모두 만족시키는 문서 이원화 구조
  • 05조직의 현재 문서화 수준을 파악하는 3가지 진단 유형 제공

RECOMMENDATION

문서화가 파편화되어 고충을 겪는 팀장이나, 사내 지식 베이스에 AI를 도입하고자 하는 엔지니어에게 실질적인 구조 설계 가이드를 제공합니다.

The Problem

문서화 실패의 주요 원인으로 '자율적 기여의 연속성 부족'과 '자신의 지식이 틀릴 수 있다는 심리적 부담감'이 지적되었습니다. 또한, 조직의 성격에 따라 문서의 독자와 업데이트 주기가 달라 일관된 전략을 적용하기 어렵다는 배경이 있습니다.

The Solution

질문이 자연스러운 분위기를 조성하기 위해 '상담 주간' 이벤트를 개최하고, AI 챗봇을 도입하여 질문 답변 및 문서 생성 현황을 정량적으로 모니터링했습니다. 또한, 사람이 읽기 좋은 중앙 문서와 AI 처리를 위한 상세 문서를 분리하여 관리하는 이원화 구조를 도입했습니다.

The Result

문서화 수준을 수치로 명확하게 파악할 수 있게 되었으며, 질문과 답변의 허들을 낮춤으로써 지식 공유가 활발해지는 효과를 얻었습니다. 특히 조직 특성에 맞춘 독자 설정과 문서 종류 분류를 통해 문서의 실질적 활용도를 높였습니다.

Trade-off

AI 가독성을 위해 상세한 디테일을 포함하면서도 사람이 읽기에 복잡하지 않게 문서를 분리함에 따라, 문서 관리 체계가 이중화되어 유지보수 관점에서의 구조적 복잡성이 증가했습니다.

03

Key Concepts

Concept · 01

Technical Writing

복잡한 기술 정보를 독자의 니즈에 맞춰 명확하고 체계적으로 전달하는 전문적인 글쓰기 기법입니다.

  • 중앙 관리 문서와 개별 레포지토리 문서의 역할 분리
  • 개발 지식이 없는 독자도 이해할 수 있는 눈높이 설정
Concept · 02

AI Knowledge Management

LLM과 챗봇 기술을 활용하여 조직 내부의 파편화된 지식을 수집, 분류하고 구성원에게 효과적으로 전달하는 관리 체계입니다.

  • 상담 챗봇 '이씨'를 통한 질문 장벽 완화
  • 매일 지식을 배달하는 '하씨' 봇을 통한 자동화된 지식 공유
Concept · 03

Documentation Metrics

문서의 신규 생성량, 질문 답변 성공률, 업데이트 주기 등을 데이터로 지표화하여 조직의 지식 공유 상태를 측정하는 도구입니다.

  • AI를 활용한 주간 문서 현황 자동 집계
  • 질문 채널 모니터링을 통한 부족한 지식 테마 식별