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

문서화 플랫폼을 만들어도 반복 기여가 이어지지 않고, 봇을 운영해도 질문 자체를 부담스러워하는 등 조직마다 다른 장벽이 드러났다. 이를 해결하기 위해 질문 이벤트와 매일 지식을 전하는 봇으로 참여 문화를 만들고, AI를 활용해 질문·답변과 문서 현황을 살폈다. AI가 읽을 세부 맥락은 팀 레포지토리에, 사람이 보기 좋은 문서는 중앙에 두는 식으로 문서의 독자와 용도도 구분했다. 문서화를 시작할 때는 지식을 한곳에 모으고 현재 상태와 구체적인 필요를 진단해, 그 문제에 맞는 문서부터 만드는 것이 중요하다는 교훈을 얻었다.

• 문서화 플랫폼은 첫 기여를 유도하는 것보다 반복 기여가 이어지도록 운영 구조를 만드는 일이 어렵다.
• 질문을 공개하는 부담은 이벤트와 일상적인 지식 공유로 낮추고, 완성된 문서 대신 기존 정보에 짧게 보태는 참여부터 유도할 수 있다.
• AI가 읽을 세부 맥락과 사람이 읽기 좋은 문서는 독자와 용도에 따라 중앙 문서와 팀 레포지토리로 분리할 수 있다.
• 문서 종류를 가이드·정책·용어 사전·지표 등으로 나누고, 각 문서의 독자와 목적을 분명히 한다.
• 문서화를 시작하기 전에는 업무가 막힐 때 사람들이 무엇을 하는지 살펴보고, 구체적인 문제에 맞는 문서부터 만든다.