우리 팀의 문서화는 왜 실패할까? (2) (새 탭에서 열림)

두 조직의 문서화 경험은 자율적 기여만으로는 지식이 지속적으로 축적되기 어렵다는 점을 보여준다. 문서화의 핵심은 흩어진 지식을 한곳에 모으고, 질문과 공유에 대한 심리적 부담을 낮추며, 조직의 상태에 맞는 구조와 운영 방식을 만드는 데 있다. AI는 문서 작성과 지식 전파를 쉽게 할 뿐 아니라, 질문·문서 증가량·답변 품질 등을 지표로 파악하게 해 문서화 상태를 진단하는 도구가 되고 있다.

자율적 문서화의 한계

• 커머스에서는 구성원이 자율적으로 참여하는 ‘커머스 위키’를 만들기 위해 워크숍과 길드를 운영했다.
• 첫 문서를 작성하게 만드는 데는 성공했지만, 두 번째·세 번째 기여로 이어지게 하기는 어려웠다.
• 문서화가 개인의 의지와 자발성에만 의존하면 지속 가능한 운영 구조를 만들기 어렵다.
• 반면 이미 문서가 잘 갖춰진 애즈 도메인에서는 새 플랫폼을 만들기보다 기존 컨벤션을 존중하고, 지식의 위치와 연결 관계를 파악하기 쉽게 만드는 데 집중했다.
• 문서가 거의 없는 조직과 이미 충분한 문서가 있는 조직은 출발점과 우선순위가 달라야 한다.

지식 공유를 막는 심리적 부담

• 질문을 적게 하는 이유는 단순히 관심이 부족해서가 아니라, “내가 모른다”는 사실을 공개하는 것이 부담스럽기 때문이다.
• 문서를 작성할 때도 “내 지식이 틀리면 어떡하지”라는 불안 때문에 좋은 자료를 공유하지 못하는 경우가 많다.
• 이를 해결하기 위해 ‘개발 상담 주간’을 열어 질문 자체를 자연스러운 행동으로 만들었다.
  • 특정 전문가에게 자유롭게 질문하도록 유도
  • 다른 사람의 질문에 공감하도록 장려
  • 전문가가 답하지 못한 질문에는 팀원들이 대신 답변하도록 독려
• 매일 짧은 서버 개발 지식을 전달하는 봇도 운영한다.
  • 구성원이 직접 문서를 찾지 않아도 지식에 노출된다.
  • 완성된 문서를 처음부터 작성하는 대신, 공유된 내용에 한마디를 보태거나 수정하는 방식으로 참여 장벽을 낮춘다.

AI가 낮춘 문서화의 진입장벽

• AI를 이용하면 문서 초안을 빠르게 만들 수 있어 문서 작성에 필요한 부담이 줄어든다.
• 챗봇은 매일 지식을 전달하거나 질문에 답하면서 지식 공유를 일상적인 활동으로 만든다.
• AI는 문서화 현황을 정량적으로 확인하는 데도 활용된다.
  • 챗봇에 올라온 질문 수
  • 사람이 대신 답변한 사례와 답변 내용
  • 일주일 동안 새로 작성된 문서 수
  • 지난주 대비 문서 증가량
  • 새로 추가된 문서 목록
• 이를 통해 어떤 지식이 부족한지, 구성원이 무엇을 궁금해하는지, 지식이 실제로 순환하고 있는지를 파악할 수 있다.

사람용 문서와 AI용 세부 문서의 분리

• AI가 문서를 읽게 되면서 사람에게는 불필요한 세부 맥락까지 기록해야 하는 상황이 생겼다.
• 커머스에서는 문서를 두 영역으로 나누었다.
  • 중앙 문서: Technical Writer가 관리하며 사람이 읽기 쉽고 조직 전체에 공유할 만한 내용 중심
  • 팀 저장소 문서: 업무 과정에서 자동으로 쌓이며 팀 내부 AI가 활용할 수 있는 세부 정보와 맥락 포함
• 문서의 독자가 사람뿐 아니라 AI까지 확장되면서, 문서의 목적과 공개 범위를 구분하는 구조가 필요해졌다.

도메인과 챕터의 차이

• 공통 원칙은 지식을 한곳에 모으고, 문서가 흩어지지 않도록 통로를 단순화하는 것이다.
• 도메인 문서
  • 제품과 코드에 직접 연결된다.
  • 제품 출시와 변화가 빠르므로 문서 업데이트 주기도 짧다.
  • 용어, 기능, 정책, 지표처럼 업무와 직접 관련된 구조가 중요하다.
  • 독자가 다양하므로 비개발자도 이해할 수 있는 수준으로 작성하는 것이 효과적이다.
• 챕터 문서
  • 특정 직군을 위한 컨벤션, 업무 방식, 생산성 지식이 중심이다.
  • 코드와 직접 관련되지 않은 추상적인 내용이 많다.
  • 변화가 느린 만큼 지속적인 업데이트와 참여를 유도하는 방식이 과제다.
  • 독자가 비교적 명확해 목적에 맞춘 문서 작성이 쉽다.

문서 유형과 독자 구분

• 하나의 문서에 모든 정보를 담기보다 독자와 목적에 따라 문서를 분리해야 한다.
• 활용 예시는 다음과 같다.
  • 가이드: 업무를 수행하는 방법 설명
  • 기능 단위 정책: 제품이나 기능의 동작 원칙 정리
  • 용어 사전: 조직 내 공통 언어 정의
  • 지표 문서: 기능이나 정책을 측정하는 기준 설명
• 문서 유형별 역할을 명확히 하면 독자가 필요한 정보를 더 빠르게 찾을 수 있다.

문서화 수준 진단 방법

• 업무 중 막혔을 때 무엇을 먼저 찾는지 관찰하면 조직의 문서화 수준을 파악할 수 있다.
• 사람이나 사내 메신저를 찾는 경우
  • 문서가 거의 없는 상태다.
  • 업무에 가장 자주 필요한 정보부터 하나씩 정리해야 한다.
• 문서를 검색하는 경우
  • 원하는 정보를 찾지 못한다면 부족한 문서를 보완해야 한다.
  • 검색이 잘 된다면 문서는 충분히 쌓인 상태이며, AI를 연결해 접근성을 높일 수 있다.
• 문서 기반 AI나 봇에게 질문하는 경우
  • 답변이 부정확하면 원인을 분석해야 한다.
  • 관련 문서가 없으면 새로 작성해야 한다.
  • 정보가 여러 곳에 흩어져 있으면 한곳으로 통합해야 한다.
  • 문서는 있지만 엉뚱한 답을 하면 내용이 오래됐거나 맥락이 부족할 가능성이 크다.

문서화의 구체적인 시작점

• “문서화를 해야 한다”는 막연한 목표보다 실제 문제와 니즈를 먼저 정의해야 한다.
• 예를 들어:
  • 팀마다 용어가 달라 소통이 어렵다면 용어 사전부터 만든다.
  • 다른 팀이나 외부에 공유할 레퍼런스가 없다면 공통 가이드를 만든다.
  • 반복적으로 질문이 발생한다면 해당 업무의 절차와 판단 기준을 문서화한다.
• 문제를 하나로 좁히고 그 문제를 해결하는 문서부터 시작해야 지속 가능성이 높다.

결국 효과적인 문서화는 구성원의 의지에만 기대지 않고, 지식을 한곳에 모으고 자연스럽게 공유되도록 만드는 운영 구조에서 출발한다. 먼저 조직의 현재 상태와 가장 큰 문서화 니즈를 진단한 뒤, 하나의 구체적인 문제를 해결하는 문서와 자동화부터 시작하는 것이 좋다.