우리 팀의 문서화는 왜 실패할까? (1)
문서화가 실패하는 이유는 구성원의 의지 부족보다 문서 작성이 개인의 결심에만 의존하는 구조에 있습니다. 무엇을 어디까지 써야 하는지 기준이 없고, 지식의 정확성을 확신하기 어렵고, 문서화가 업무 프로세스에 자연스럽게 포함되지 않기 때문입니다. 도메인과 챕터 모두에서 출발점은 흩어진 지식을 한곳에 모아 실제 업무에 활용되도록 만드는 것이었습니다. ## 도메인과 챕터의 문서화 차이 - **도메인** - 커머스·광고처럼 특정 사업이나 제품을 목표로 여러 직군이 협업하는 조직입니다. - 정책, 용어, 제품 지식, 실험 결과, API 등 업무와 직접 연결된 정보를 다룹니다. - **챕터** - 서버·프론트엔드처럼 같은 직군이 모인 기능 조직입니다. - 컨벤션, 도구 사용법, 기술 표준, 운영 경험 등 직군 공통 지식을 공유합니다. ## 조직별 문서화 활동 - 동진 님은 커머스와 애즈 도메인에 흩어진 내부 지식을 연결하고, 개발자센터와 문서 업데이트 프로세스를 운영합니다. - 혜빈 님은 전사 문서화 기준과 문서 시스템 ‘토독’을 만들고, 서버 챕터에서는 문서화 길드를 운영합니다. - 문서 작성뿐 아니라 문서 리뷰, 자동화, 지식 공백 탐색까지 문서화의 범위를 넓히고 있습니다. ## 조직의 기대와 실제 반응 - 커머스 도메인에서는 구성원들이 이미 구체적인 문서화 요구를 갖고 있었습니다. - 용어가 통일되지 않아 불편함 - 제품에 적용 중인 정책을 찾기 어려움 - 실험 문서와 API 문서가 제대로 정리되지 않음 - 서버 챕터에서는 처음에 문서화의 효용보다 작성에 드는 수고를 더 크게 느꼈습니다. - 문서를 기반으로 답변하는 AI 챗봇도 원천 문서가 부실해 효과가 제한적이었습니다. - 이후 문서화 길드가 챗봇의 답변을 모니터링하고 부족한 문서를 보완하면서, 문서가 실제 도구의 품질을 높인다는 점을 구성원들이 체감하게 됐습니다. ## 인터뷰로 확인한 실제 문제 - 동진 님은 구성원 인터뷰를 통해 도메인에서 필요한 지식과 문서 공백을 파악했습니다. - 혜빈 님은 온보딩 문서 리뷰가 작성자에게 부담이 되는지 확인하기 위해 인터뷰를 진행했습니다. - 예상과 달리 구성원들은 리뷰를 긍정적으로 받아들였습니다. - 공개 전 다른 관점에서 검토할 수 있음 - 초안보다 문서 품질이 향상됨 - 문서화의 핵심 장애물은 의지 부족이 아니라 작성 방법의 불확실성이었습니다. - 무엇을 다뤄야 하는지 모름 - 어느 수준까지 작성해야 하는지 모름 - 자신의 지식이 정확한지 확신하기 어려움 - 틀린 정보를 공유할까 봐 공개를 꺼림 ## 문서가 없을 때 발생하는 협업 비용 - 도메인에서는 정책과 정보가 여러 팀에 흩어져 협업이 지연됩니다. - 예를 들어 B팀이 정산 기능을 수정하려면 먼저 기존 정산 정책의 위치부터 찾아야 합니다. - 온보딩 과정에서도 체계적인 문서가 없으면 자신이 무엇을 모르는지조차 파악하기 어렵습니다. - 챕터에서는 코드만으로 이해하기 어려운 운영상의 예외나 설계 배경을 찾는 데 많은 시간이 듭니다. - 과거 메신저 스레드를 검색하거나 - 여러 검색어로 반복해서 찾거나 - 최종적으로 코드를 작성한 사람에게 직접 물어봐야 합니다. - 개인이 해결한 오류와 업무 지식을 공유하지 않으면 같은 문제를 구성원들이 반복해서 해결하게 됩니다. - “이 정도는 모두 알겠지”, “나만 모르는 것 같다”는 심리적 장벽이 지식 공유를 막습니다. ## 문서화가 개인의 의지에 의존하는 구조 - 문서화는 당장 효과가 나타나기보다 6개월 후, 1년 후에 가치가 커지는 미래를 위한 투자입니다. - 현재 업무와 직접 연결되지 않으면 부수적인 일로 밀리기 쉽습니다. - 문서를 한 번 작성하는 데서 끝나지 않고 지속적인 업데이트 책임도 필요합니다. - 따라서 작성자는 문서화를 가치 있는 자산보다 추가적인 책임이나 부담으로 느낄 수 있습니다. - 작성과 수정이 업무 프로세스에 포함되어 있지 않으면, 바쁜 상황에서 문서화는 쉽게 중단됩니다. - AI는 초안 작성과 정리를 도와 문서화의 도구적 장벽을 낮추지만, 문서화 기준과 운영 구조 자체를 대신 만들지는 못합니다. ## 문서화의 출발점 - 조직에 필요한 문서를 먼저 파악하려면 구성원 인터뷰와 실제 업무의 불편을 관찰해야 합니다. - 완벽한 문서를 한 번에 만들기보다 흩어진 지식을 우선 한곳에 모으는 것이 중요합니다. - 이후 검색, 리뷰, AI 챗봇 등 실제 사용 사례를 통해 부족한 문서를 발견하고 개선해야 합니다. - 문서화가 지속되려면 작성·리뷰·업데이트가 개인의 의지가 아니라 업무 흐름에 자연스럽게 포함되어야 합니다.
원문 읽기(새 탭에서 열림)