토스 프론트엔드 개발자들이 더 이상 문서를 찾지 않는 이유

새로운 기능을 개발하다 보면 이런 순간이 찾아와요. 모니터에는 수십 개의 탭이 열려있고, 팀 내부 도구 사용법을 찾아보려는데 문서가 어디 있는지조차 기억나지 않죠. 결국 동료에게 메시지를 보내고 답장을 기다리면서 개발 흐름이 끊기고 맙니다. 익숙한 상황이죠?

토스 프론트엔드 챕터도 비슷한 문제를 경험하고 있었는데요. 이 문제를 조금 다르게 풀어 봤습니다. 문서를 더 잘 써서 방문하게 하는 대신, 문서가 직접 찾아가는 방식으로요.

문서의 경로의존성 깨기

문서의 경로의존성은 사용자가 원하는 정보를 찾기 위해 정해진 경로를 따라가야 하는 제약을 뜻해요. 기존의 기술 문서는 생산자 입장에서 구조화되어 있어서 사용자 입장에서 원하는 정보를 찾으려면 여러 번의 탐색, 혹은 검색이 필요하죠. 이런 문서의 경로의존성을 깨기 위해 먼저 개발자들이 어떻게 일하는지 관찰하고, 인터뷰했어요.

개발자들이 지식을 얻기 위해 주로 사용하는 방식은 “질문하기”였어요. 옆에 있는 동료에게 물어보거나, 사내 메신저 채널에 질문을 던지는 거죠. 자연스럽고 공감되는 행동이었어요. 그래서 이런 개발자의 행동을 존중하는 방식으로 문서의 형태를 바꿔보기로 했습니다.

질문하기의 가장 큰 장점은 원하는 정보를 즉각적으로 얻을 수 있다는 거예요. 방대한 문서를 검색하고 읽는 것보다 동료에게 직접 물어보는 것이 시간과 노력 면에서 훨씬 효율적이에요. 개발자들이 문서를 더 적극적으로 활용하게 하려면, 이러한 즉각성이 문서에도 필요하다고 생각했어요. 마치 대화하듯이 문서에 질문을 던졌을 때 맥락에 맞는 답변을 바로 받을 수 있다면, 문서는 더욱 강력한 도구가 될 거예요.

그렇게 탄생한 도구가 바로 ‘박씨’에요.

박씨: 질문하면서 문서 읽기

• 특징: 질문하면 문서 내용을 기반으로 답변해줘요. 일의 흐름이 끊기지 않고 바로바로 정보를 얻을 수 있어요.
• 위치: IDE(VSCode, Cursor)와 사내 메신저에 있어요.
• 효과: "문서 찾기"가 아닌 "대화하듯 물어보기”로 지식을 얻을 수 있어요.
• 재밌는 점: 박씨는 프론트엔드 챕터 헤드 서진님의 페르소나를 따서 만들어 졌어요.

박씨는 LLM이 더 정확하고 신뢰할 수 있는 답변을 만들어내기 위해 개발된 RAG(Retrieval-Augmented Generation) 기반 챗봇이에요. 기존 문서들을 바탕으로 믿을 수 있는 정보를 답변하고, 그 출처를 함께 제공해요. 박씨를 사용하면 문서를 탐색하거나 키워드로 검색할 필요 없이, 궁금한 점을 자연스럽게 물어보면서 필요한 정보를 얻을 수 있어요. 동료에게 물어보는 것보다 더 정확하고, 누구에게나 일관된 답변을 제공한다는 장점이 있죠.

박씨가 좋은 품질의 답변을 하려면 탄탄한 기반 지식이 필요해요. 그래서 저희는 문서의 양과 질을 모두 높이는 것에도 많은 공을 들이고 있어요. 하지만 테크니컬 라이터와 소수의 개발자들만으로는 충분한 문서를 만들기 어려웠어요. 이 시스템이 확장성을 가지려면 누구나 자신의 지식을 쉽게 문서화할 수 있어야 했죠. 그래서 실록봇이라는 문서 자동화 도구를 만들었답니다.

실록봇: 대화를 바로 문서화하기

• 역할: 사내 메신저 대화 속 중요 정보를 쉽게 문서화해요.
• 작동방식: 대화 스레드에 실록봇 이모지를 붙이거나 봇을 호출하면 AI가 대화를 분석하고 요약해서 PR을 올려요.
• 효과: 사람이 시간을 내서 문서를 따로 작성하는 것이 아니라, 실제 문제 해결 과정에서 자연스럽게 그리고 자동으로 기록할 수 있어요.

실록봇은 팀 내에서 오가는 중요한 대화를 요약해서 자동으로 문서화 해줘요. 사실 개발자들은 사내 메신저에서 질문에 답하거나 대화하며 항상 지식을 교류하고 있더라구요. 그런 대화가 메신저에서 일어나기 때문에 빠르게 휘발되고, 반복적으로 같은 질문이 올라오는 게 아쉬웠어요. 실록봇은 메신저에서 일어나는 대화를 요약해서 문서 리포지토리에 PR을 만들어요. 메신저에 남긴 유용한 메시지나 논의 스레드를 최소한의 노력으로 기록할 수 있게 된 것이죠.

예를 들어, 어떤 버그를 해결하기 위해 나눈 대화가 도움이 됐다고 생각한 팀원이 실록봇을 호출해요. 그러면 그 대화는 바로 문서가 되고, 이렇게 만들어진 정보는 박씨가 학습해요. 덕분에 팀원들은 같은 질문을 반복할 필요 없이 실록봇이 모은 정보와 박씨를 사용해 쉽게 해결책을 찾을 수 있어요. 문서를 위한 문서 작성이 아니라, 지식이 공유되는 순간에 자연스럽게 문서가 만들어지는 거예요.

지식이 흐르는 팀

박씨와 실록봇 덕분에 이제 토스 프론트엔드 챕터는 특정 팀원에게 지식이 몰려있거나, 같은 질문이 반복되는 문제가 줄었어요. 필요한 순간에 필요한 정보가 제공되면서 팀 내 지식이 자연스럽게 흐르는 환경이 되었답니다. 그리고 이런 환경이 팀의 생산성과 효율성을 높이고 있어요. 개발자의 행동을 관찰하고, ‘기술 문서’를 정적인 정보 모음이 아니라 개발자의 학습과 문제 해결을 도와주는 시스템으로 접근했던 것이 유효했어요.

테크니컬 라이팅도 함께 진화하고 있는데요. 이전에는 공급자 관점에서 정보를 구조화하고 특정 기능을 효과적으로 설명하는 것에 초점을 맞췄다면, 지금은 개발자가 문서를 잘 사용할 수 있는 시스템을 만드는 데 집중하고 있어요. 결국 테크니컬 라이팅의 본질은 ‘어떻게 문서로 개발자의 문제 해결을 도와줄 수 있을까’이기 때문이에요.

토스 프론트엔드 플랫폼 팀은 지식을 공유하고, 접근하기 좋은 학습 인프라를 만드는 여정에 함께하실 분을 기다리고 있어요. AI 기반 문서화 시스템을 더욱 발전시키고, 코드와 자연스럽게 연결되는 문서 자동화 시스템을 만들고, 사내 메신저를 비롯한 여러 플랫폼과 잘 어우러지는 문서 생태계를 구축하는 일들이 기다리고 있어요.

개발자들이 더 효율적으로 일할 수 있는 환경을 만들어서 개발자 경험을 한 단계 높이는 일에 관심 있으신가요? 그렇다면 Frontend Platform Engineer에 지원해 주세요! 함께 더 나은 개발 문화를 만들어가요.