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

조직에서 누구나 한 번쯤 들어봤을 말이 있습니다. "우리 문서화 해야 합니다." 그리고 그 말은 대부분 한 달쯤 가다 흐지부지됩니다. 왜 그럴까요?

Technical Writing Chapter의 동진 님, 혜빈 님은 각각 다른 조직에서 이 문제를 풀고 계신데요. 동진 님은 커머스라는 '도메인'에서, 혜빈 님은 서버라는 '챕터'에 직접 들어가 문서화를 맡았습니다. 성격이 다른 두 조직에서 같은 문제를 어떻게 풀었는지 이야기를 들어봤습니다.

우리의 일을 소개합니다

Q. 각자 요즘 어떤 일을 하시는지 간단히 소개해 주세요.

황동진(이하 동진): 커머스와 애즈 도메인에서 다양한 곳에 쌓이는 내부 지식을 한곳으로 모으고 연결하는 시스템을 만들고 운영하는 일을 하고 있어요. 그 외에도 외부에 문서를 서비스하는 개발자센터와 문서 업데이트 프로세스를 멤버들과 함께 만들고 있습니다.

김혜빈(이하 혜빈): 저는 Knowledge System Team(이하 놀리지 팀)에서 '토독(todoc)'이라는 문서 시스템을 만들고 있는데요. 이 제품을 만들면서 전사에 적용할 수 있는 문서화 기준을 만들고, 문서 작성이나 리뷰 자동화 같은 것들을 고도화하고 있습니다.

한편으로는 서버 챕터에서 문서화 길드를 운영하며 조직의 지식이 잘 공유되도록 문서를 작성하거나, 어떤 정보가 부족한지 찾는 여러 활동을 진행 중이에요.

기대와 달랐던 것들

Q. 각자 조직에서 문서화를 하겠다고 했을 때 사람들은 어떻게 받아들이던가요? 기대했던 것과 실제가 달랐던 점이 있었나요?

동진: 저는 합류하고 보니 오히려 다른 분들이 문서화에 대해 더 잘 알고 계셨던 것 같아요. 그분들이 완벽한 답을 갖고 있었다기보다는, '문서화가 이 조직에서 어떻게 정의되어야 하는지'를 소통하면서 제가 많이 배운 부분이 있어요.

Q. 오, 어떤 걸 보면서 그렇게 느끼셨어요?

동진: 조직마다 니즈가 확실한 부분들이 있었어요. "용어 정리가 안 되고 있어 불편하다. 용어부터 문서화되면 좋겠다", "지금 어떤 정책이 제품에 적용되고 있는지 확인하기 어려우니 정리해달라" 같은 거요. 어떤 것을 문서로 남겨야 하는지에 대한 요구가 굉장히 확실했어요. 글쓰기 기준 같은 건 없어도, 어떤 문서가 업무에 도움이 되는 좋은 문서인지에 대한 기준이 확실한 분들이 많았어요. 그래서 '좋은 문서가 업무 현장에 실제로 이런 도움을 줄 수 있구나, 혹은 있어야 하는구나'를 깨달았죠.

주연: 어떻게 보면 참 좋은 시기에 들어오신 거네요. 사람들이 이미 문서화를 하고 싶어 하는 상황이었으니까요. 혜빈 님, 챕터는 어땠어요? 문서화에 대한 의지가 있었나요?

혜빈: 처음에는 문서화에 대해 미온적이라고 느꼈어요. 지금까지 문서 없이 일해왔고 문서의 효용을 제대로 느낄 기회도 없었기 때문에, 문서가 주는 효용보다 당장의 수고로움을 대부분 더 크게 느끼셨던 것 같아요.

예를 들어 서버 챕터에서는 문서를 참조해서 답변해주는 AI 챗봇(이하 이씨)을 만드는 등, 문서화 길드가 생기기 전부터 문서를 활용하려는 시도를 해왔어요. 하지만 이씨 답변의 재료가 되는 문서가 제대로 정리돼 있지 않다 보니, 답변이 제대로 되지 않아 효용을 느끼지 못했고요.

그런데 지금은 길드에서 이씨의 답변을 모니터링하면서 부족한 문서를 보강하니, 이씨의 답변 퀄리티가 좋아지는 걸 실감하시는 것 같아요. 이런 지식이 쌓이는 게 실제로 쓸모 있다는 걸 점점 체감하고 계시는 거죠.

인터뷰로 발견한 문제

Q. 이제 실제로 일하신 과정을 들어볼게요. 두 분 다 구성원 분들을 인터뷰하셨더라고요. 문서화 업무를 위해 인터뷰를 하게 된 이유가 뭐였나요?

동진: 우리 도메인에 어떤 지식이 필요한지, 어떤 공백이 있어서 불편함을 느끼는지를 알고 싶어서였어요. 그래서 개발자분들께 여쭤봤죠. 실험 문서가 잘 정리됐으면 좋겠다, API 문서도 잘 됐으면 좋겠다 같은 얘기가 나왔어요. 어떤 부분을 기록으로 남겨야 할지 알고 싶어서 인터뷰를 시작했던 것 같아요.

주연: 원하는 정보를 얻으셨어요?

동진: "우리 도메인에 이런 니즈가 있구나"는 인터뷰를 통해 확실히 알았어요. 다만 그걸 해결하는 건 당연하지만 또 다른 문제이긴 하더라고요.

주연: 혜빈 님은 처음부터 인터뷰를 많이 하기보다 일을 하다가 중간에 인터뷰를 하셨던 걸로 기억해요. 그 접근은 어땠나요?

혜빈: 처음 서버 챕터에서 맡았던 업무는 "온보딩 문서 리뷰하기"였는데요. 당시 개발자 분들에게 리뷰를 엄청나게 꼼꼼하게 드리고, 문서 작성이 밀리는 분들께 여러 번 독촉도 했어요. 동시에 개발자 분들 입장에서 이런 문서 리뷰가 귀찮고 번거로운 것이라고 생각하시지 않을까, 문서 리뷰가 까다롭다고 느껴서 문서화 자체를 더 부담스럽게 느끼시는 건 아닐까 하는 걱정이 들었거든요.

그래서 온보딩 문서를 작성했을 당시 어떤 점이 어려웠는지, 그 과정이 어떻게 개선될 수 있을지 직접 들어보려고 인터뷰를 진행했어요.

그런데 실제로 제가 걱정하던 것처럼 생각하는 분들은 없으시더라고요. 오히려 작성한 문서를 공개하기 전에 다른 사람의 시각으로 리뷰를 받아볼 수 있어서 좋았고, 직접 작성한 초안과 비교했을 때 문서 퀄리티가 눈에 띄게 좋아져서 감사했다는 의견이 대부분이었습니다.

또, 문서 작성 동기가 없는 게 아니라 문서화를 하기 어려운 상황이라는 것도 알게 되었어요. "어떤 지식을 어떻게, 어디까지 다루어야 할지 모르겠다", "문서를 쓰더라도 내가 아는 지식이 정확한지에 대한 확신이 없어서 공유하기가 꺼려진다" 같은 구체적인 어려움을 발견할 수 있었어요.

문서화가 안 되면 생기는 일들

Q. 도메인과 챕터는 목적 조직과 기능 조직이잖아요. 각각의 조직에서 문서화가 되어 있지 않으면 어떤 문제가 생기던가요? 먼저 도메인 쪽부터요.

동진: 일단 협업할 때 어려움이 있어요. 예를 들어 정산 정책을 A팀이 관리하는데, B팀이 정산 기능 관련 개발을 하면서 스펙을 변경해야 하는 상황이라고 가정해 볼게요. 그러면 B팀은 "기존 정산 정책이 어디 있지?"부터 찾기 시작해야 하는 상황이 생겨요. 이렇게 지식이 흩어져 있으면 팀들이 협업할 때 정책이나 정보를 찾는 게 생각보다 큰 병목이 되더라고요.

온보딩 때도 마찬가지예요. 일차적으로 정리된 내용이 있으면 내가 뭘 모르고 뭘 아는지 파악할 수 있는데, 한곳에 정리가 안 돼 있으면 '내가 뭘 모르는지조차 모르는' 상태가 훨씬 길어져요. 정리가 되어 있으면 그 모르는 것이 무엇인지도 모르는(unknown unknowns) 상태를 확 줄여주는 역할을 하는 것 같아요.

혜빈: 챕터에서도 비슷했어요. 좋은 코드라면 주석이나 외부 문서 없이 코드만으로 무슨 일을 하는지 읽혀야 한다지만, 실제로 일하다 보면 늘 그렇게 짤 수는 없어요. 운영이나 개발 환경 상의 이슈 때문에 언뜻 보면 이상해 보이는 코드를 써야 할 때가 있거든요. 이럴 때는 코드만 보고 왜 이렇게 짰는지 알 수 없어서, 맥락이나 히스토리를 따로 찾아봐야 해요.

그런데 이런 히스토리를 찾는 데 시간을 많이 쓴다고 하시더라고요. 몇 년 전 사내 메신저 스레드까지 내려가서 검색하고, 안 되면 다른 검색어로 또 찾고, 그래도 안 되면 작성자를 찾아가 직접 여쭤보고요. 개발 자체보다 히스토리를 찾고 리스크를 가늠하는 데 드는 시간이 컸어요.

또 다른 문제는 조직 안에서 정보를 공유하는 환경 자체가 만들어지지 않는다는 거였어요. 서버 개발자분들 중에는 업무하면서 알게 된 내용이나 에러 해결법을 문서로 잘 정리해두신 분이 꽤 많았는데요. 대부분 그걸 공유하기 보다는 개인적으로만 간직(?)하고 계시더라고요. (웃음)

회사에서 개발자 커뮤니티는 서로의 지식을 나누는 것 자체가 중요한 자산이잖아요. 특히 챕터처럼 같은 직군이 모인 기능 조직은 흩어져서 일하더라도 '서버 개발'이라는 공통의 지식을 함께 쌓고 나누라고 모여 있는 거고요. 그런데 다들 개인적으로만 쓰다 보니 거기에 심리적인 허들이 생기는 거예요. '이 정도는 다들 알겠지' 싶어 안 꺼내고, '나만 모르나 보다' 싶어 묻지도 않고요. 결국 이미 정리된 지식이 보이지 않고, 어떤 지식이 필요한지도 드러나지 않으니, 같은 지식을 각자 따로 알아내느라 챕터 전체의 생산성이 떨어지는 거예요.

주연: 맞아요. 특히 기술 조직에서 그런 경우를 많이 봐요. "이거 나만 모르는 거 아닌가, 별거 아닌 지식 아닌가" 해서 아예 혼자만 모아두시는 경우가 많았던 것 같아요. 두 조직 다 지식이 한곳에 모여 있는 게 제일 중요하군요.

문서화는 의지의 문제다?

Q. 여기까지 들으니 한 가지가 궁금해져요. "문서 잘 쓰자", “문서가 중요하다”는 말은 정말 많은 조직에서 합니다. 그런데 왜 잘 안 될까요? 직접 조직에 들어가서 해보신 입장에서요.

동진: 문서화는 '지금'을 위한 일이 아니라 '나중'을 위한 일이라서 늘 후순위가 되는 것 같아요. 오늘 잘 정리해 놓는다고 내일 당장 다시 찾아보지 않을 걸 아니까요. 이미 내 머릿속에 있고, 특히 기능 조직에서는 지금 진행 중인 일이기도 하고요. 그런데 6개월 뒤, 1년 뒤가 되면 굉장히 소중한 기록이 될 수 있는 건데, 그때까지 내다보면서 일하기는 참 쉽지 않은 것 같아요. 특히 문서화는 약간 부수적인 업무처럼 여겨지다 보니, 꾸준히 잘하기가 어려운 것 같아요.

혜빈: 맞아요. 문서화가 부수적인 업무로 느껴지는 데다가 의식적으로 "내가 이걸 해야겠다" 하고 시간을 따로 내야 하니, 마음먹기까지가 오래 걸리기도 해요. 또 한번 쓰고 끝이 아니라, 쓴 사람이 계속 신경 써서 내용을 업데이트해야 하는 책임도 따라오고요. 그러니 문서가 미래를 위한 투자라기보다 책임이나 짐처럼 느껴지는 것 같아요.

결국 문제는 문서는 항상 '개인의 의지'로 시작된다는 점 같아요. 막상 쓰면 얼마 안 걸리는데도, 그 결심을 하는 비용이 크다 보니 바쁘면 우선순위에서 밀려나거든요. 작성이나 수정이 업무 프로세스에 자연스럽게 끼어 있다면 굳이 마음먹지 않아도 문서가 쌓일 텐데, 그렇지 않으니 지속되지 않는 거죠.

동진: 혜빈 님 말에 공감해요. 그리고 예전에 회의에서 들었던 얘기가 기억나는데, "근데 중요한 일이면 어려워도 해야 되는 거 아니에요?"라는 말이었어요. (일동 웃음) 문서화가 정말 중요하고 임팩트가 크다면 당연히 어려워도 해야 한다는 거죠. 그래서 의지의 문제가 분명히 없진 않은 것 같다는 생각도 들어요.

그리고 AI가 나오고 나서 문서화 온도가 올라간 이유 중 하나가, AI를 활용하면 문서 쓰는 게 좀 쉬워져서거든요. 그런 도구적인 허들 같은 것도 문서화가 안 되는 이유 중 하나가 아닐까 싶습니다.

지금까지 두 분이 해주신 이야기를 정리하면, 문서화가 늘 실패하는 이유는 의지가 부족해서가 아니었습니다. 무엇을 어디까지 써야 할지 기준이 없고, 내 지식이 틀릴까 두렵고, 무엇보다 '쓰겠다는 결심'에만 기대야 하는 구조 자체가 문제였죠. 그리고 두 조직이 도달한 시작점은 같았습니다. 일단 흩어진 지식을 한곳에 모으는 것이죠.

다음 편에서는 두 사람이 각자의 조직에서 이 문제를 어떻게 풀어왔는지부터 그 과정에서 AI가 일으킨 변화, 그리고 이제 막 문서화를 시작하는 조직이 무엇부터 손대면 좋을지까지 이야기 나눠볼게요.