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

앞선 인터뷰에서는 문서화가 늘 실패하는 이유를 알아봤습니다. 의지가 약해서가 아니라, 쓸 기준도 확신도 없는 데다 '쓰겠다는 결심'에만 의존하는 구조가 문제였고, 그래서 흩어진 지식을 한곳에 모으는 것이 중요하다는 이야기였죠.

그렇다면 혜빈 님과 동진 님은 실제로 어떻게 이 문제를 해결하고 있을까요? 이번 편에서는 도메인과 챕터라는 서로 다른 조직에서 겪은 시행착오부터, AI가 문서에 일으킨 변화, 그리고 이제 막 문서화를 시작하는 조직이 무엇부터 시작하면 좋을지 이야기 나눠볼게요.

문제 해결 과정

Q. 막상 진행해 보니 처음 잡은 문서 구조나 문서화 방식이 맞지 않거나, 예상과 달랐던 게 있었나요?

동진: 저는 처음에 커머스 위키라는 문서를 사람들이 자율적으로 기여할 수 있는 플랫폼으로 만들려고 했어요. 워크숍이나 길드를 통해 기여하는 법을 계속 알려드리면 자율적으로 기여하는 분들이 점점 늘지 않을까 생각했죠. 그런데 워크숍에 초대해서 첫 문서를 쓰게 하는 것까지는 되는데, 그다음 두 번째, 세 번째, 네 번째 기여로 계속 연결되게 만드는 게 굉장히 어렵더라고요. 자율적으로 운영되는 구조를 만드는 게 쉽지 않다는 걸 느꼈죠.

주연: 지금은 애즈(Ads) 도메인도 맡으셨잖아요. 자율 플랫폼이라는 시도 대신, 거기서는 어떻게 접근하고 계세요?

동진: 애즈는 이미 문서화를 꽤 잘하고 계시더라고요. 내부 문서 툴들에 문서가 잘 갖춰져 있고, 최신화된 문서도 많고, 각 제품을 찾으면 다 확인되는 상황이에요. 그래서 애즈에서는 이미 운영 중인 컨벤션을 최대한 존중해서, 새로운 걸 만들기보다는 어떤 지식이 어디에 있는지 잘 파악할 수 있도록 도와드리는 게 낫겠다는 생각이 들었어요.

주연: 문서가 아예 없는 조직과 어느 정도 있는 조직은 처음에 해야 할 일이 다르네요.

동진: 그런 것 같아요.

혜빈: 저는 초반에 봇이 해주는 답변을 모니터링하면서 부족한 부분을 채우면, 개발자분들이 봇을 더 편하게 쓰실 수 있겠다고 생각했어요. 그런데 모니터링을 하려고 보니 애초에 봇에 질문하는 분이 많지 않더라고요. 그게 예상 밖이었어요.

왜 그럴까 인터뷰를 해보니, 질문을 한다는 건 곧 '내가 이걸 모른다'를 공개적으로 드러내는 일이라 그 자체가 부담이었던 거예요. 그리고 이건 문서를 쓸 때도 똑같았어요. 챕터 지식은 다른 분들이 보고 실제 업무에 적용하는 거잖아요. 그래서 '내가 아는 게 틀렸으면 어쩌지' 하는 공포가 크시더라고요. 좋은 자료인데도 정확한지 확신이 안 서서 혼자서만 정리하고 있거나, 비슷한 문제를 겪는 사람이 주변에 있을 때에만 공유하고요.

질문이 안 나오는 것이든 문서가 안 모이는 것이든, 결국 '내 지식이 틀릴까 봐'라는 같은 지점에서 막히고 있던 거예요. 그래서 지금은 그 부담부터 덜어드리고 있어요.

주연: 그 부담을 어떻게 덜어드리고 있나요?

혜빈: 크게 두 가지를 하고 있어요.

하나는 질문하고 답하는 게 자연스러운 분위기를 만드는 거예요. 아까 말씀드린 것처럼 질문을 하는 것 자체가 내가 모른다는 사실을 드러내는 일이라 부담스러워하시잖아요. 그래서 '이씨의 개발 상담 주간'이라는 이벤트를 열었어요. 일주일 동안 이씨에게 마음껏 질문해보는 기간인데요. 이씨에게 질문하는 것뿐만 아니라, 다른 사람 질문에 공감하고, 이씨가 답하지 못하는 질문은 대신 답변하도록 독려해서 지식 공유가 활발한 분위기를 만들려고 했어요. 나만 모르나 싶어 묻지 못하던 분도, 다들 질문하는 주간이라고 하면 한결 편하게 느끼거든요. 이씨가 답변하지 못하더라도 다른 팀원들이 나서서 답변해줄 거라는 믿음도 가질 수 있고요.

다른 하나는 모르는 것을 알아서 찾아보거나 질문하지 않아도 알 수 있도록 만드는 거예요. '하씨'라는 봇을 운영하고 있는데, 하루에 한 번씩 짧은 서버 개발 지식을 전달해요. 직접 문서를 찾아 읽지 않아도, 채널에 있기만 하면 지식이 공유되는 거죠. 여기서 '어, 이건 우리 팀 상황이랑 좀 다른데' 싶으면 가볍게 제보하거나 바로잡아 주시고요. 처음부터 완성된 문서를 쓰라고 하면 부담스럽지만, 이미 공유되는 지식에 한마디 보태는 건 훨씬 쉽거든요.

주연: 문화적인 노력도 중요하군요.

AI가 바꾼 문서화

Q. 이제 문서를 AI가 읽고 쓰는 시대가 됐잖아요. 이런 변화가 문서를 다룰 때 어떤 영향을 주었나요? 거기에 어떻게 대응하셨는지도 궁금해요.

혜빈: 저는 AI 덕분에 조직 단위의 문서화가 훨씬 수월해졌다고 느껴요. 크게 두 가지인데요.

하나는 문서를 쓰고 공유하는 일 자체가 쉬워졌어요. 예전엔 문서 한 편 쓰는 게 큰맘 먹어야 하는 일이었는데, 이제는 AI로 초안을 빠르게 만들 수 있으니까요. 그리고 앞서 말씀드린 이씨나 하씨 같은 챗봇으로 지식을 전파할 수도 있고요. 이런 챗봇이 매일 지식을 공유하거나 질문에 답해주면서 지식 공유의 허들이 낮아진 것 같아요.

다른 하나는 AI를 사용해서 지식이 조직 안에서 얼마나 잘 돌고 있는지를 확인할 수 있게 됐어요. 사실 문서화가 잘 되고 있다는 건 막연한 감으로만 느끼기 쉽잖아요. 그래서 서버 챕터에서는 이씨의 질문 답변 현황을 AI와 함께 모니터링하고 있어요. 질문이 몇 개 올라왔는지, 이씨 대신 답변을 남긴 사람이 있는지, 사람이 대신 답변했다면 어떻게 답변했는지를 AI가 모아서 정리해요. 문서 현황을 알기 위해서 한 주 동안 토독(todoc)에 올라온 문서가 몇 개인지, 지난주 대비 얼마나 늘었는지, 새로 올라온 문서는 무엇인지도 확인하고요.

이렇게 지표로 만들면 지금 우리 조직의 문서 현황이 어떻고, 어떤 지식이 부족한지, 사람들이 무엇을 궁금해 하는지가 바로 보여요. 예전 같으면 일일이 채널을 들여다봐야 했을 텐데, 이제는 명확한 수치로 파악할 수 있는 거죠.

동진: 저도 AI 덕에 편해진 면은 분명히 있는데, 한편으로는 새로운 고민도 같이 생기더라고요. AI가 읽을 문서에는 사람에게는 굳이 필요 없는 디테일까지 들어가는 경우가 많거든요.

그래서 커머스에서는 문서를 두 갈래로 나눴어요. 중앙에 Technical Writer가 관리하는 문서가 있고, 각 팀 레포지토리에는 업무하면서 자동으로 쌓이고 업데이트되는 문서가 따로 있어요. 이렇게 나눈 이유가, "이런 내용은 우리 팀 AI한테만 필요한 맥락인데 다 같이 보는 문서에 굳이 올려야 하나, 올려도 되나" 하는 고민을 다들 많이 하시더라고요. 그게 오히려 문서를 쓰는 데 허들이 됐어요.

그래서 중앙에 있는 문서는 좀 더 사람이 보기 좋게 두고(물론 AI도 활용할 수 있고요), 각 팀 레포에는 각자에게 세부적이고 다른 팀엔 불필요할 수 있는 디테일까지 기록하는 형태로 나눈 거예요. 이 구조 자체가, 문서를 사람만 읽는 게 아니게 되면서 생긴 결과라고 볼 수 있을 것 같아요.

문서화를 시작하려는 분들께

Q. 도메인이든 챕터든 공통으로 지켜야 할 문서화 원칙이나 전략이 있을까요? 반대로, 조직 성격 때문에 반드시 달라야 하는 건요?

혜빈: 공통으로 지켜야 할 건 일단 지식이 한곳에 모여 있는 것, 통로가 너무 다양해지지 않는 것이라고 생각해요. 그래야 조직에 지식이 얼마나 쌓였는지, 어떤 게 필요한 문서이고 아닌지를 파악할 수 있으니까요. 도메인이든 챕터든 지식을 한곳에 모으는 게 가장 중요하고, 가장 먼저 해야 할 일이라고 생각해요.

동진: 혜빈 님이 너무 잘 말씀해 주셨는데요. 사실 지금 하는 작업도 결국 흩어진 걸 한곳으로 모으는 일이라, 인터뷰하면서 "커머스에서 고민하던 걸 똑같이 고민하고 계시는구나" 싶었어요. 오히려 차이점보다 공통점이 많은 것 같은데, 차이가 있다면 뭘까요?

주연: 제가 생각나는 건, 도메인은 코드 기반으로 문서를 만들거나 확인할 수 있다는 점이에요. 제품이 계속 나가니 제품과 연결해서 문서화하는 게 중요하고, 용어도 그래서 중요하고요. 반면 챕터는 코드와 상관없는 문서가 많잖아요. "이 챕터에서는 이런 컨벤션을 지켜야 한다", “이렇게 일해야 한다” 같은 거요. 물론 라이브러리처럼 코드와 연관된 것도 있지만, 아닌 경우도 많은 것 같아요.

또 문서가 업데이트 되는 속도도 다른 것 같아요. 제품 기반일 때는 주기가 너무 빨라서 못 따라가는 문제가 있었고, 챕터는 반대로 잘 바뀌지 않으니 이걸 어떻게 계속 쓰게 하고 유지하게 할지가 고민인 거죠.

혜빈: 동의해요. 주연 님 말씀처럼, 챕터는 훨씬 추상화된 부분이 많은 것 같아요. 도메인은 목적을 위해 일하는 조직이라 속도도 빠르고 본인 업무와 직접 연관되잖아요. 그런데 챕터는 당장 업무를 처리하는 것보다는 좀 더 '생산성'에 가까운 지식을 축적하는 것 같아요. "이걸 하면 이 직군으로서 일을 더 잘할 수 있다, 더 깊이 이해할 수 있다, 이런 문제를 해결할 수 있다"는 측면으로 접근하는 거죠.

동진: 저는 독자를 어떻게 설정하고 문서를 쓰는가가 제일 다른 것 같아요. 챕터는 특정 직군을 위한 거라 목적도 독자가 확실한데, 도메인은 "도메인 전체를 위해 쓴다"고 하면 독자가 너무 다양해서 애매해지는 경우가 많거든요.

주연: 그러게요. 동진 님은 그러면 어떻게 독자를 설정하고 문서를 쓰세요? 구조는 어떻게 만들고요?

동진: 일단 '개발을 모르는 분도 이해할 수 있어야 한다'를 전제로 가요. "개발자가 읽는 문서다" 생각하고 쓰면, 막상 개발자 분들도 자기 분야가 아니면 다른 분야에 대한 이해가 떨어지는 경우가 꽤 있더라고요. 그래서 비개발자도 이해할 수 있게 눈높이를 높여서 써야 많은 분이 이해할 수 있게 되는 것 같아요.

그리고 문서 종류를 잘 나눠놨어요. 크게 가이드가 있고, 기능(Capability) 단위로 정리된 정책이 있고, 용어 사전이 있고, 거기에 지표(Metric)가 붙어 있고요. 이렇게 문서 종류를 잘 나눠서 각 종류가 확실한 가치를 전달할 수 있게 하는 게 중요한 것 같아요. 독자와 니즈에 따라 다르게요.

주연: 하나의 문서로 다 하기보다, 다양한 독자에 맞게 각각의 문서를 제공하는 게 중요하겠군요.

Q. 마지막 질문입니다. 지금 막 문서화를 시작하려는 조직에게, 가장 먼저 시도하면 좋은 한 가지를 제안해 주신다면요?

혜빈: 지금 그 조직의 문서화 수준이 어느 정도인지 진단하는 게 우선이에요. 업무를 하다가 막히는 게 있을 때 가장 먼저 무엇을 하는지를 떠올려보면 쉽게 파악할 수 있어요. 답변은 여러 가지가 될 수 있겠지만 크게 세 유형으로 나눠볼게요.

1. 사람에게 물어보거나 사내 메신저를 찾아본다: 문서화가 거의 안 되어 있어서 처음부터 쌓아야 하는 상황이에요. 조직에 가장 필요한 정보부터 하나씩 정리해 나가면 돼요.
2. 문서를 직접 검색한다: 검색을 통해 원하는 정보를 쉽게 얻을 수 있는지 떠올려 보세요. 검색으로 원하는 정보를 잘 못 찾겠다면 결국 사람에게 직접 물어보게 될 거라, 부족한 문서부터 채워야 해요. 만약 원하는 정보를 잘 찾고 있다면 문서는 충분히 쌓여 있는 거예요. 문서를 검색하는 수고를 덜고 싶다면, 문서와 AI를 연결해서 접근성을 높일 수 있어요.
3. 문서를 바탕으로 답변하는 AI나 봇에게 질문한다: AI나 봇이 정확하게 잘 답변하는지를 확인하면 돼요. 사실 문서화를 시작해야겠다고 느끼는 조직이라면 봇이 제대로 답하지 못하고 있을 가능성이 큰데, 왜 제대로 답변하지 못한다고 느끼는지 파악해 보세요. 예를 들어, 애초에 그 주제를 다룬 문서가 없었다면 그 주제를 다루는 문서를 새로 써야 해요. 혹은 정보가 여기저기 흩어져 있어서 봇이 제대로 찾지 못하는 경우일 수도 있어요. 문서는 있는데 봇이 엉뚱하게 답한다면 내용이 낡았거나 문서에 담긴 맥락이 부족하다는 신호고요.

이렇게 업무를 하다가 막힐 때 무엇인지 스스로 답한 다음, 왜 그렇게 하고 있는지를 따라가다 보면 우리 조직의 문서에서 손봐야 할 지점이 자연스럽게 드러나요.

동진: 저는 '문서화를 해야겠다고 느끼는 이유, 그 니즈가 뭔지'를 명확히 하는 게 중요하다고 생각해요. 문서화는 워낙 범위가 넓어서, 조직에서 막연히 "먼저 해야 돼" 하고 시작하면 뭐부터 해야 할지 애매해지거든요. 그래서 커머스처럼 "우리는 지금 용어 소통이 안 되니 용어 사전부터 정리한다"든지, "외부에 나가거나 다른 팀에 공유해야 하는데 레퍼런스가 없으니 그것부터 정리한다"든지, 문제를 구체적으로 정리하고 거기에 딱 맞는 문서를 만드는 데 집중해서 시작하는 게 좋은 출발일 것 같아요.

도메인과 챕터, 성격이 다른 두 조직에서 두 사람이 도달한 답은 같았습니다. 흩어진 지식을 한곳에 모으고, 조직이 지금 어느 상태인지 진단하고, 그리고 사람이 애쓰지 않아도 지식이 모이고 흐르는 구조를 만드는 것이죠.

저희 챕터는 그 구조를 만드는 일을 중점적으로 하고 있는데요. 다음 글에서는 저희가 조직의 지식을 쌓는 것을 어떻게, 어디까지 자동화했는지 공유드릴게요.