개발자가 문서를 발견하는 방법 (Toss)

*이 글은 이전에 발행된 기사의 영어 버전입니다.

모든 개발자는 이 경험을 해봤을 겁니다. 새로운 기능을 깊게 만들고 있고, 탭은 서른 개가 열려 있는데, 갑자기 내부 도구가 어떻게 작동하는지 찾아봐야 합니다… 그런데 문서가 어디에 있는지조차 기억나지 않습니다. 그래서 팀원에게 메시지를 보내고 기다립니다. 그렇게 당신의 흐름(flow)이 끊어집니다. 이런 경험을 해본 적 있나요?

이는 저희 프론트엔드 챕터가 너무나 잘 알고 있던 문제였습니다. 그래서 우리는 다른 접근 방식을 시도했습니다. 문서를 더 찾기 쉽게 만드는 대신, 개발자에게 다가가게 만들기로 한 것입니다.

문서의 경로 의존성 깨기 (Breaking Path Dependence in Documentation)

문서의 경로 의존성이란 사용자가 필요한 정보에 도달하기 위해 미리 정해진 경로를 따라가도록 강제하는 제약입니다. 전통적인 기술 문서는 작성자의 관점에서 구조화되어 있기 때문에, 원하는 것을 정확히 찾는 것이 여러 번의 검색을 필요로 하는 경우가 많습니다. 이 패턴을 깨기 위해, 우리는 개발자들이 실제 작업 환경에서 어떻게 일하는지 관찰하고 그들에게 실제로 일을 처리하는 방법에 대해 인터뷰하기 시작했습니다.

개발자들이 지식을 얻는 주된 방식은 단순히 '질문'하는 것이었습니다. 어깨를 톡 치거나, 답을 알 수도 있는 팀원에게 슬랙(Slack)으로 빠르게 메시지를 보내는 식입니다. 이는 자연스러우며, 솔직히 말해 매우 합리적입니다. 문서 페이지들을 검색하는 것은 30초 대화가 필요로 하는 시간과 노력을 필요로 합니다. 그래서 우리는 그 본능에 맞서기보다는 그것을 활용하기로 했습니다.

우리는 문서가 똑같은 즉각성을 가질 수 있도록, 마치 참고 매뉴얼이 아니라 지식이 풍부한 동료처럼 응답하도록 만들려면 무엇이 필요한지 스스로에게 물었습니다. 질문받는 정확한 맥락에 맞는 정보를 가져와 답변하는 문서야말로 사용해 볼 만한 문서입니다.

그리고 그렇게 Mr. Park가 탄생했습니다.

Mr. Park: 당신의 문서에 말을 걸어보세요

Mr. Park: 문서에 질문을 던져보세요

• 작동 방식: 질문을 하고 문서에서 바로 답변을 얻습니다
• 찾을 수 있는 곳: IDE (VSCode, Cursor) 및 회사 메신저
• 기능: '탐색'이 아닌 '대화'를 통해 정보를 찾습니다
• 재미있는 사실: Mr. Park는 프론트엔드 챕터 리더인 박소진 님의 페르소나에서 이름을 따왔습니다.

Mr. Park는 LLM 답변을 더 정확하고 신뢰할 수 있게 만들기 위해 구축된 RAG(검색 증강 생성) 기반 챗봇입니다. 기존 문서를 활용하여 신뢰할 수 있는 답변을 제공하며, 항상 출처를 첨부합니다. 개발자들은 문서를 열거나 검색을 실행할 필요 없이 자연스럽게 질문하고 필요한 정보를 얻을 수 있습니다. 그 답변은 팀원에게 받는 것보다 더 정확하며, 누가 질문하든 일관성이 유지됩니다.

Mr. Park가 양질의 답변을 제공하려면 참고할 견고한 지식 기반이 필요합니다. 그래서 저희는 문서의 양과 질 모두를 개선하는 데 심혈을 기울였습니다. 하지만 기술 작가와 소수의 개발자만으로는 충분한 커버리지를 만들 수 없었습니다. 이 시스템이 확장되기 위해서는 개인의 지식을 쉽게 문서화할 방법이 필요했습니다. 이것이 바로 저희가 문서 자동화 도구인 Sillokbot을 구축하게 된 계기입니다.

Sillokbot: 대화를 자동으로 문서화하세요

• 기능: 회사 메신저 대화에서 핵심 정보를 자동으로 문서화합니다
• 작동 방식: Sillokbot 이모티콘으로 스레드에 반응하거나 봇을 직접 호출합니다. 대화를 분석하고 AI를 사용하여 요약한 다음, PR(Pull Request)을 생성합니다.
• 도움되는 점: 문제가 해결됨과 동시에 지식이 자동으로 포착되어, 누군가 앉아서 별도의 문서를 작성할 필요가 없습니다.

Sillokbot은 팀 내에서 발생하는 중요한 대화 내용을 자동으로 요약합니다. 문제는 개발자들이 이미 회사 메신저에서 지식을 교환하며 질문에 답하고 문제들을 논의해 왔다는 것입니다. 어려웠던 점은 이러한 대화 내용이 빠르게 사라지고, 같은 질문들이 계속해서 반복된다는 것이었습니다. Sillokbot은 이 흐름을 포착하여 요약한 다음, 문서 저장소(documentation repository)로 PR(Pull Request)을 열어 유용한 논의 내용을 거의 추가적인 노력 없이도 보존합니다.

개발자가 버그 수정 과정에서 특정 스레드가 특히 유용했다는 것을 깨달았다고 가정해 봅시다. 그들은 Sillokbot에게 이 스레드를 요청하고, 순식간에 전체 논의 내용이 박 씨가 배울 수 있는 문서로 변환됩니다. 다음 질문을 가진 사람은 같은 논의 내용을 열어보지 않고도 답변을 얻게 됩니다. 문서화 작업이 별도의 숙제가 아니라, 지식이 공유되는 바로 그 순간 자연스럽게 일어나기 시작합니다.

흐르는 지식 (Knowledge that Flows)

박 씨와 Sillokbot 덕분에 Toss 프론트엔드 챕터의 지식은 더 이상 특정 한 사람에게만 집중되지 않으며, 같은 질문들이 팀 내에서 돌고 도는 일도 없어졌습니다. 적절한 정보가 적절한 순간에 사람들에게 전달되고, 지식은 마땅히 흘러야 할 방향으로 움직입니다. 이는 팀의 생산성과 효율성에 직접적인 영향을 미쳤습니다. 투자가 결실을 맺었습니다. 개발자들이 실제로 어떻게 작업하는지 관찰하고 기술 문서를 정적인 정보의 집합체가 아닌 학습 및 문제 해결 시스템으로 다루면서, 우리는 실질적인 결과를 얻었습니다.

기술 작문(Technical writing)은 이 모든 과정과 함께 진화했습니다. 예전에는 작성자의 관점에서 정보를 구조화하고 기능을 잘 설명하는 데 초점을 맞췄습니다. 이제는 문서를 개발자를 위해 실제로 작동하게 만드는 시스템을 구축하는 데 초점을 맞추고 있습니다. 왜냐하면 결국 기술 작문은 항상 개발자들에게 문서를 진정으로 유용하게 만드는 것에 관한 것이었기 때문입니다.

Toss Frontend Platform Team은 지식을 쉽게 공유하고 접근할 수 있는 학습 인프라를 구축하는 데 함께 할 사람들을 찾고 있습니다. AI 기반 문서 시스템을 더욱 발전시키거나, 코드와 자연스럽게 연결되는 문서 자동화 기능을 구축하거나, 회사 메신저 및 다른 플랫폼 전반에 걸쳐 원활하게 작동하는 문서 생태계를 만드는 것과 같이 앞으로 해야 할 일이 많이 남아있습니다.

개발자들이 최고의 역량을 발휘할 수 있는 환경을 구축하는 것이 당신이 원하는 도전처럼 들린다면 저희와 함께해 주세요.